API Reference

API Documentation

Base URL: https://api.taxoai.dev

Authentication

All authenticated endpoints require an X-API-Key header. API keys are prefixed with cat_.

curl -H "X-API-Key: cat_your_api_key" https://api.taxoai.dev/v1/usage

Quick Start (30 seconds)

1. Get your free API key
curl -X POST https://api.taxoai.dev/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My Store"}'
2. Analyze your first product
curl -X POST https://api.taxoai.dev/v1/products/analyze \
  -H "X-API-Key: cat_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Blue Polo Shirt", "description": "100% cotton", "language": "en"}'

Endpoints

POST /v1/register Public No auth

Create account and get your first API key. No credit card required.

POST /v1/products/analyze Core

Classify a single product synchronously. Returns taxonomy, SEO content, and attributes.

POST /v1/products/batch Batch

Submit up to 500 products for async batch processing. Returns a job ID.

GET /v1/jobs/{job_id} Batch

Poll the status and results of a batch job.

GET /v1/taxonomies/search Utils

Search Google Shopping taxonomy categories by keyword.

GET /v1/usage Account

Get your current monthly usage stats (products used, limit, reset date).

POST /v1/keys Account

Create an additional API key (up to 10 per account).

GET /v1/keys Account

List all active API keys for your account.

DELETE /v1/keys/{id} Account

Revoke an API key.

GET /v1/health Public No auth

Check API health status (PostgreSQL and Redis connectivity).

Error Codes

Code Status Description
200 OK Request successful. Response body contains the result.
201 Created Resource created successfully (e.g., new API key or account).
400 Bad Request Invalid request body or missing required fields. Check the error message for details.
401 Unauthorized Missing or invalid X-API-Key header.
403 Forbidden Your plan does not include this feature, or you've reached your API key limit.
404 Not Found The requested resource (job, key) does not exist.
409 Conflict Email already registered. Use your existing API key or request a reset.
422 Unprocessable Entity Request body is valid JSON but contains semantic errors (e.g., invalid language code).
429 Too Many Requests Rate limit exceeded. Check Retry-After header for when to retry.
500 Internal Server Error Unexpected server error. Contact support if it persists.
503 Service Unavailable API is temporarily down for maintenance. Check the status page.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": "short_error_code",
  "message": "Human-readable description of the error",
  "status": 400
}

Rate Limits

Plan Req/min Req/day Products/month
Free 10 150 100
Starter 60 3,500 3,000
Pro 200 16,000 15,000
Agency 500 65,000 60,000
Get your free API key