Alterscope Developer API

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.

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

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.

​Top-level fields

​The _agentic block

​Response headers

​Reading it as an agent

Top-level fields

The `_agentic` block

Response headers

Reading it as an agent