API Documentation

Build powerful integrations with Convexify Services API

Base URLhttps://services.convexify.tech/api/v1

Overview

The Convexify Services API provides programmatic access to powerful data extraction and analysis tools. Currently available services include:

🔍

Reviews Scraping

Extract product reviews from major retailers including Sephora, Ulta, and Macy's. Get ratings, review text, sentiment analysis, and more.

Available

📊

Sentiment Analysis

Advanced AI-powered sentiment analysis for any text content with detailed emotion detection and theme extraction.

Coming Soon

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header:

Request Header

X-API-Key: cvx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Need an API key? Contact us at javier@convexify.tech to get started.

Endpoints

POST/reviews/scrape

Scrape product reviews from a supported retailer URL.

Supported Retailers

SephoraUlta BeautyMacy'sAmazon (Soon)Nordstrom (Soon)

Request Body

JSON

{
  "url": "https://www.sephora.com/product/product-name-P12345",
  "maxReviews": 100,        // Optional. Default: 100, Max: 500
  "includeRawData": false   // Optional. Include raw API response
}

Example Request

cURL

curl -X POST https://services.convexify.tech/api/v1/reviews/scrape \
  -H "X-API-Key: cvx_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.sephora.com/product/mini-powder-blush-P511166",
    "maxReviews": 50
  }'

Response

JSON Response (200 OK)

{
  "success": true,
  "data": {
    "retailer": "sephora",
    "productId": "P511166",
    "productName": "Mini Talc-Free Powder Blush",
    "totalReviews": 1234,
    "avgRating": 4.5,
    "reviews": [
      {
        "id": "review-12345",
        "rating": 5,
        "title": "Amazing product!",
        "text": "I love this blush, the color is perfect and lasts all day...",
        "date": "2025-01-15",
        "reviewer": {
          "name": "BeautyLover",
          "location": "New York"
        },
        "helpfulVotes": 42,
        "verifiedPurchase": true
      }
      // ... more reviews
    ],
    "summary": {
      "sentiment": {
        "positive": 78,
        "neutral": 15,
        "negative": 7
      },
      "themes": {
        "positive": ["pigmented", "long-lasting", "beautiful colors"],
        "negative": ["price", "small size"]
      },
      "notableQuotes": [
        {
          "text": "Best blush I've ever used!",
          "rating": 5,
          "helpfulVotes": 156
        }
      ]
    },
    "scrapedAt": "2025-01-24T12:00:00Z"
  },
  "meta": {
    "method": "bazaarvoice",
    "requestId": "req_abc123xyz",
    "processingTimeMs": 2500,
    "creditsUsed": 1
  }
}

Response Headers

Header	Description
`X-Request-Id`	Unique request identifier for debugging
`X-RateLimit-Remaining`	Remaining requests in current minute
`X-Processing-Time-Ms`	Server processing time in milliseconds

GET/usage

Retrieve your API usage statistics for the current billing period.

Query Parameters

Parameter	Type	Default	Description
`period`	string	current_month	current_month, last_month, or all

Example Request

cURL

curl https://services.convexify.tech/api/v1/usage?period=current_month \
  -H "X-API-Key: cvx_live_xxxxxxxx"

GET/health

Check API status. No authentication required.

Example Response

JSON Response (200 OK)

{
  "status": "healthy",
  "service": "convexify-services",
  "version": "1.0.0",
  "timestamp": "2025-01-24T12:00:00Z"
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

Code	Status	Description
`200`	OK	Request successful
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key inactive or quota exceeded
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal server error

Error Response Format

JSON

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not from a supported retailer",
    "details": {
      "url": "https://example.com/product",
      "supportedRetailers": ["sephora", "ulta", "macys"]
    }
  }
}

Rate Limits

Rate limits are applied per API key to ensure fair usage:

Plan	Requests/Min	Monthly Quota	Support
Free	10	1,000 reviews	Email
Starter	30	10,000 reviews	Email
Pro	60	50,000 reviews	Priority
Enterprise	Custom	Unlimited	Dedicated

Credits System: API usage is measured in credits. Each request costs max(1, ceil(reviews / 100)) credits. For example, scraping 250 reviews costs 3 credits.

Code Examples

Python

import requests

API_KEY = "cvx_live_xxxxxxxx"
BASE_URL = "https://services.convexify.tech/api/v1"

def scrape_reviews(product_url, max_reviews=100):
    response = requests.post(
        f"{BASE_URL}/reviews/scrape",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "url": product_url,
            "maxReviews": max_reviews
        }
    )
    return response.json()

# Example usage
result = scrape_reviews(
    "https://www.sephora.com/product/mini-powder-blush-P511166",
    max_reviews=50
)
print(f"Found {len(result['data']['reviews'])} reviews")

JavaScript / Node.js

JavaScript

const API_KEY = "cvx_live_xxxxxxxx";
const BASE_URL = "https://services.convexify.tech/api/v1";

async function scrapeReviews(productUrl, maxReviews = 100) {
  const response = await fetch(`${BASE_URL}/reviews/scrape`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      url: productUrl,
      maxReviews: maxReviews
    })
  });
  return response.json();
}

// Example usage
const result = await scrapeReviews(
  "https://www.sephora.com/product/mini-powder-blush-P511166",
  50
);
console.log(`Found ${result.data.reviews.length} reviews`);

Need Help?

Have questions or need support? Reach out to us:

Email: javier@convexify.tech
GitHub: github.com/convexifytech