API Documentation

1. Create an Account

Sign up for an account at facetize.io/signup.

2. Add Credits

Add credits to your account from your billing page. Each API request costs $0.01, so you'll need credits before making any requests.

3. Generate an API Key

Navigate to your API keys page and create a new API key. Give it a descriptive name to help you manage multiple keys.

4. Make Your First Request

Use the interactive tester in your dashboard or make a request using curl:

curl -X POST https://facetize.io/api/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "blue t-shirts under $50"
  }'

Bearer Token Format

Include your API key in the Authorization header using the Bearer token format:

Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx

API keys start with the prefix facetize_

Example Request

curl -X POST https://facetize.io/api/translate \
  -H "Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "red running shoes"
  }'

Security Best Practices

• Never expose your API keys in client-side code or public repositories
• Use environment variables to store API keys securely
• Rotate API keys regularly, especially if you suspect unauthorized access
• Use different API keys for different applications or environments
• Monitor your API usage regularly to detect any suspicious activity

Invalid API Key Response

If your API key is missing or invalid, you'll receive a 401 Unauthorized response:

{
  "error": "Invalid or expired API key"
}

Tier System

Your API tier (1-10) determines your rate limits. New accounts start at tier 1, and tiers automatically increase based on your account age and usage patterns.

Rate Limit Headers

Every API response includes rate limit information in the response headers:

• X-RateLimit-Limit-Minute - Maximum requests per minute
• X-RateLimit-Remaining-Minute - Remaining requests in current minute
• X-RateLimit-Reset-Minute - When the minute window resets (ISO 8601)
• X-RateLimit-Limit-Hour - Maximum requests per hour
• X-RateLimit-Remaining-Hour - Remaining requests in current hour
• X-RateLimit-Reset-Hour - When the hour window resets (ISO 8601)
• X-RateLimit-Limit-Day - Maximum requests per day
• X-RateLimit-Remaining-Day - Remaining requests in current day
• X-RateLimit-Reset-Day - When the day window resets (ISO 8601)

Rate Limit Exceeded

When you exceed your rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before making another request.",
  "tier": 1,
  "limits": {
    "perMinute": { "limit": 10, "remaining": 0, "reset": "2024-01-01T12:01:00Z" },
    "perHour": { "limit": 100, "remaining": 50, "reset": "2024-01-01T13:00:00Z" },
    "perDay": { "limit": 1000, "remaining": 900, "reset": "2024-01-02T00:00:00Z" }
  },
  "retryAfter": 45
}

The Retry-After header indicates how many seconds to wait before retrying.

POST /api/translate

Translates natural language ecommerce queries into structured taxonomy filters. The endpoint uses AI-powered query parsing combined with vector similarity search to match queries to the taxonomy database.

{
  "query": string,        // Required: Natural language query (1-255 characters)
  "context": string       // Optional: Context to help disambiguate (max 255 characters)
}

{
  "categories": {
    "gid1": {
      "name": "Apparel",
      "confidence": 0.95
    }
  },
  "attributes": {
    "gid2": {
      "name": "Color",
      "confidence": 0.92,
      "values": {
        "gid3": {
          "name": "Blue",
          "confidence": 0.88
        }
      }
    }
  },
  "vendors": ["Nike", "Adidas"],
  "priceRange": {
    "min": 10,
    "max": 50
  },
  "gtin": ["1234567890123"],
  "modelNumbers": ["SKU-ABC123", "MOD-XYZ456"],
  "availability": true,
  "tags": ["sale", "new-arrival"],
  "collections": ["Summer"],
  "queryTerms": ["iPhone 15 Pro", "Nike Air Max"],
  "options": [...]
}

curl -X POST https://facetize.io/api/translate \
  -H "Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "blue t-shirts under $50",
    "context": "this is a clothing store"
  }'

{
  "categories": {
    "gid_123": {
      "name": "Apparel",
      "confidence": 0.95
    }
  },
  "attributes": {
    "gid_456": {
      "name": "Color",
      "confidence": 0.92,
      "values": {
        "gid_789": {
          "name": "Blue",
          "confidence": 0.88
        }
      }
    },
    "gid_101": {
      "name": "Product Type",
      "confidence": 0.85,
      "values": {
        "gid_102": {
          "name": "T-Shirt",
          "confidence": 0.82
        }
      }
    }
  },
  "vendors": [],
  "priceRange": {
    "max": 50
  },
  "gtin": [],
  "modelNumbers": [],
  "availability": undefined,
  "tags": [],
  "collections": [],
  "options": [
    {
      "name": "Color",
      "values": ["Blue"]
    },
    {
      "name": "Product Type",
      "values": ["T-Shirt"]
    }
  ]
}

curl -X POST https://facetize.io/api/translate \
  -H "Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find product with GTIN 1234567890123, model SKU-ABC123 that is in stock"
  }'

{
  "categories": {},
  "attributes": {},
  "vendors": [],
  "priceRange": undefined,
  "gtin": ["1234567890123"],
  "modelNumbers": ["SKU-ABC123"],
  "availability": true,
  "tags": [],
  "collections": [],
  "options": []
}

Status Codes

{
  "error": "Invalid request body",
  "details": "query: Query is required"
}

{
  "error": "Invalid or expired API key"
}

{
  "error": "Internal server error",
  "message": "Failed to process request"
}

Error Response Format

All error responses follow a consistent format:

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": "Optional additional details"
}

Handling Errors

When implementing error handling in your application:

• Check the HTTP status code first to determine the error type
• For 429 errors, respect the Retry-After header
• For 401 errors, verify your API key is correct and hasn't been revoked
• For 400 errors, check the details field for specific validation issues
• Implement exponential backoff for retries on 500 errors

Cost Per Request

Each API request costs $0.01 USD (1 cent). This includes the full processing pipeline:

• AI-powered query parsing
• Vector similarity search
• Text-based taxonomy matching
• Structured response generation

Account Balance

You maintain a prepaid balance in your account. Each successful API request deducts $0.01 from your balance. You can add credits anytime from your billing page.

Insufficient Balance

If your account balance is insufficient, you'll receive a 402 Payment Required response:

{
  "error": "Insufficient balance",
  "message": "Your account balance is too low to process this request. Please add credits to continue."
}

Monitoring Usage

Track your API usage and costs in real-time from your usage dashboard. You can view:

• Request history and logs
• Current account balance
• Usage statistics and trends
• Cost breakdown by time period