Core concepts

Response envelope

Shared success, error, metadata, and headers.

Success envelope

JSON
{
  "success": true,
  "data": {
    "query": "bhusaval",
    "results": []
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_01J...",
    "trace_id": "trc_01J...",
    "timestamp": "2026-11-20T10:57:12.762Z",
    "freshness": {
      "mode": "live",
      "retrieved_at": "2026-11-20T10:57:12.762Z",
      "sources": [
        {
          "confidence": "high"
        }
      ]
    }
  }
}

Shared fields

  • successboolean

    Whether the operation succeeded.

  • dataobject

    Endpoint-specific payload. Replaced by error on failures.

  • meta.api_versionstring

    API major used for the response.

  • meta.request_idstring

    Stable request identifier to include with support requests.

  • meta.trace_idstring

    Distributed trace identifier.

  • meta.timestampstring(date-time)

    Response creation time as an ISO instant.

  • meta.freshnessobject

    Live retrieval time and source confidence metadata.

Freshness

Live requests emit Cache-Control: no-store, no-cache, must-revalidate, private. The confidence header and freshness block report whether live sources agreed and when they last reported.

Forward-compatible parsing

  • Ignore unknown response fields.
  • Branch on success before reading data.
  • Use error.code, never parse the human message.
  • Allow unknown enum and error values to fall through to a safe default.
  • Log the request ID with operation, status, and latency.

Last updated