API Conventions
================

Base URL
--------

Use the base URL from :doc:`baseurl`.

Authentication
--------------

- Header: ``X-API-Key: <your_key>``
- All endpoints require a valid API key. Keys are managed under :doc:`../accessing_api/index`.

Content Types
-------------

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

Standard Response Envelope
--------------------------

All endpoints return a consistent shape:

.. code-block:: json

  {
    "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:

.. code-block:: json

  {
    "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``.