API Conventions

Base URL

Use the base URL from Base URL.

Authentication

Header: X-API-Key: <your_key>
All endpoints require a valid API key. Keys are managed under Authentication.

Content Types

Requests: application/json (where applicable)
Responses: application/json

Standard Response Envelope

All endpoints return a consistent shape:

{
  "success": true,
  "data": { /* object or array */ },
  "meta": {
    "api_version": "v1",
    "timestamp": "YYYY-MM-DD",
    "request_id": "req_xxx"
  }
}

Errors

400: ValidationError (e.g., missing/invalid parameters)
401: Unauthorized (missing/invalid API key)
404: NotFound (code not found)
429: RateLimited
5xx: ServerError

Example error body:

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "'query' must be at least 2 characters"
  },
  "meta": {
    "api_version": "v1",
    "timestamp": "2025-10-12",
    "request_id": "req_..."
  }
}

Rate Limits & Fair Use

Per-plan rate limits apply. The API is cloud-hosted and scales with higher plans. Contact support for volume upgrades.

Idempotency & Retries

GET requests are safe to retry. Use exponential backoff on 429/5xx.

OpenAPI

OpenAPI 3.0 spec is available at /openapi/v1.json.