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

# Response Envelope

> The standard {data, meta} envelope every Alterscope v2 response returns, including the agentic metadata block.

Every `/v2/*` endpoint returns the same JSON envelope: a top-level `data` field with the result, and a `meta` field with request metadata. On endpoints that carry the agentic extension, `meta._agentic` adds a machine-readable freshness and quality signal so an automated consumer can decide how much to trust the response before acting on it.

```json theme={null}
{
  "data": { "...": "the endpoint result (object or array)" },
  "meta": {
    "request_id": "req_…",
    "_agentic": {
      "schema_version": "1.0.0",
      "freshness": {
        "computed_at": "2026-05-26T12:00:00Z",
        "age_seconds": 4,
        "update_cadence_seconds": 60,
        "next_update_at": "2026-05-26T12:01:00Z",
        "status": "realtime",
        "should_retry": false
      },
      "confidence": 0.92,
      "sources": ["chainlink", "archive-node"],
      "quality_gate": { "verdict": "pass" }
    }
  }
}
```

## Top-level fields

| Field             | Meaning                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `data`            | The endpoint result — an object or array, shape documented per endpoint.                        |
| `meta.request_id` | Unique per request (`req_…`); echoed in the `X-Request-ID` header. Quote it in support tickets. |
| `meta._agentic`   | The agentic metadata block, present on agentic-enabled endpoints.                               |

## The `_agentic` block

| Field              | Type      | Meaning                                                                                                                                                                                                                                             |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version`   | string    | Envelope contract version. Current value: `1.0.0`. Also returned in the `X-Schema-Version` header.                                                                                                                                                  |
| `freshness`        | object    | How fresh the data is. See [Freshness & staleness](/develop/concepts/freshness-and-staleness).                                                                                                                                                      |
| `confidence`       | number    | Overall confidence in the response, `0.0`–`1.0`.                                                                                                                                                                                                    |
| `sources`          | string\[] | The data sources that backed this response, when applicable.                                                                                                                                                                                        |
| `field_confidence` | object    | Optional per-field confidence and provenance (`confidence`, `method`, `sources`, `degraded`).                                                                                                                                                       |
| `quality_gate`     | object    | Whether the response is fit for automated use: `verdict` (`pass` / `warn` / `fail`), plus optional `reason` and `degraded_fields`. Mirrored in the `X-Quality-Gate` header. See [Freshness & staleness](/develop/concepts/freshness-and-staleness). |
| `_links`           | object    | Optional HATEOAS-style links to related endpoints (`href`, `title`).                                                                                                                                                                                |
| `truncated`        | boolean   | Set when an automated-tool response exceeded its output cap and was clipped. **If `true`, do not act on the payload** — re-request with a narrower query.                                                                                           |

## Response headers

| Header             | Value                                                           |
| ------------------ | --------------------------------------------------------------- |
| `X-Schema-Version` | The `_agentic.schema_version` (e.g. `1.0.0`).                   |
| `X-Quality-Gate`   | The `_agentic.quality_gate.verdict` (`pass` / `warn` / `fail`). |
| `X-Request-ID`     | The `meta.request_id`.                                          |

A client that only needs the freshness/quality signal can read the headers without parsing the body.

## Reading it as an agent

The `_agentic` block exists so an automated consumer can make an act/wait/escalate decision from the response itself. The full agent-consumption contract is covered in [Agentic envelope](/develop/concepts/agentic-envelope).

<Note>
  The `_agentic` extension is rolling out across `/v2/*` endpoints. Endpoints that don't yet emit it return the base `{ data, meta }` envelope; both shapes are valid. See the [versioning policy](/api-reference/versioning).
</Note>