> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uapi.nl/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> Standard envelope, request metadata, and data payloads

All endpoints return a single, consistent envelope. Field order is stable:

id → success → data → error → request → uapi\_version → schema\_version → deprecation\_warnings.

`data` is populated when `success` is true. When `success` is false, `data` is null and `error` is populated.

<ResponseField name="id" type="string" required>
  Globally unique request identifier for logging, tracing, and support.
</ResponseField>

<ResponseField name="success" type="boolean" required>
  Indicates whether a structured payload was successfully produced.
</ResponseField>

<ResponseField name="data" type="object | null" required>
  Endpoint-specific payload when `success` is true.

  For `/v1/extract`, this is the normalized, schema-aligned object for the target URL.

  For `/v1/search`, this includes `answer_text` and `sources` with canonical URLs and titles.

  For `/v1/perform` (beta), this describes the action result.
</ResponseField>

<ResponseField name="error" type="object | null" required>
  Present when `success` is false. Includes a stable `code` and human-readable `message`, suitable for both programmatic handling and logs.
</ResponseField>

<ResponseField name="request" type="object" required>
  Normalized view of what uAPI executed. Designed for observability and debugging.

  <Expandable title="request fields">
    <ResponseField name="endpoint" type="string">
      Canonical endpoint path such as `/v1/extract`.
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method used, for example `GET` or `POST`.
    </ResponseField>

    <ResponseField name="params" type="object">
      Query parameters received by the API.
    </ResponseField>

    <ResponseField name="payload" type="object">
      JSON body received for write or action endpoints.
    </ResponseField>

    <ResponseField name="status_code" type="integer">
      HTTP status code returned for this request.
    </ResponseField>

    <ResponseField name="requested_at" type="timestamp">
      ISO 8601 UTC time when the request was accepted.
    </ResponseField>

    <ResponseField name="served_at" type="timestamp">
      ISO 8601 UTC time when the response was produced.
    </ResponseField>

    <ResponseField name="elapsed_ms" type="integer">
      Total processing time in milliseconds.
    </ResponseField>

    <ResponseField name="cache_info" type="object">
      Cache behavior for this request.

      <Expandable title="cache_info fields">
        <ResponseField name="is_cached" type="boolean">
          True if the response was served from cache for this API key.
        </ResponseField>

        <ResponseField name="cached_at" type="timestamp | null">
          When the cached representation was stored.
        </ResponseField>

        <ResponseField name="expires_at" type="timestamp | null">
          When the cached representation is scheduled to expire.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="uapi_version" type="string" required>
  Version of the uAPI processing pipeline used for this request. Useful for correlating behavior across deployments.
</ResponseField>

<ResponseField name="schema_version" type="string" required>
  Version of the response envelope contract. Changes only when the top-level shape semantics evolve.
</ResponseField>

<ResponseField name="deprecation_warnings" type="array" required>
  Non-fatal warnings attached to the request. Used to signal upcoming changes without breaking current integrations.
</ResponseField>

<ResponseExample>
  ```json 200 Success (root example) theme={null}
  {
    "id": "9ec63d3e-423f-4e29-8065-e8983cfaf0c1",
    "success": true,
    "data": {
      "message": "Welcome to the uAPI: Universal Natural Language API!",
      "documentation_url": "https://docs.uapi.nl",
      "status_page_url": "https://status.uapi.nl",
      "endpoints": {
        "/v1/extract": "Turns any webpage into structured JSON data.",
        "/v1/search": "Finds direct answers to natural language questions.",
        "/v1/perform": "Performs an automation or action on a webpage."
      },
      "support_email": "contact@uapi.nl"
    },
    "error": null,
    "request": {
      "endpoint": "/",
      "method": "GET",
      "params": {},
      "payload": {},
      "status_code": 200,
      "requested_at": "2025-11-08T12:40:37.292Z",
      "served_at": "2025-11-08T12:40:37.301Z",
      "elapsed_ms": 9,
      "cache_info": {
        "is_cached": true,
        "cached_at": "2025-11-08T12:40:37.000Z",
        "expires_at": "2025-11-08T12:41:37.000Z"
      }
    },
    "uapi_version": "1.2.5",
    "schema_version": "v1",
    "deprecation_warnings": []
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 200 Success (/v1/extract, truncated) theme={null}
  {
    "id": "req_extract_nvda",
    "success": true,
    "data": {
      "name": "NVIDIA Corporation",
      "symbol": "NVDA",
      "price": 180.28,
      "percent_change": -0.49,
      "volume": 161039698,
      "currency": "USD",
      "timestamp": "2025-10-23T09:00:00Z"
    },
    "error": null,
    "request": {
      "endpoint": "/v1/extract",
      "method": "GET",
      "params": {
        "url": "https://finance.yahoo.com/quote/NVDA/"
      },
      "payload": {},
      "status_code": 200,
      "requested_at": "2025-10-23T09:05:18.802Z",
      "served_at": "2025-10-23T09:05:35.299Z",
      "elapsed_ms": 16497,
      "cache_info": {
        "is_cached": false,
        "cached_at": null,
        "expires_at": null
      }
    },
    "uapi_version": "1.2.5",
    "schema_version": "v1",
    "deprecation_warnings": []
  }
  ```
</ResponseExample>

<Note>
  Your integration should rely on this envelope shape: read `success`, then `data` or `error`, and log `id` plus `request` fields for observability. SDKs expose these fields via typed models while preserving the exact wire format.
</Note>