Alterscope Developer API

The agentic envelope is the meta._agentic block attached to wrapped /v2 responses. It exists so an automated consumer can make an act / wait / escalate decision from the response itself — without bespoke per-endpoint handling. It tells an agent:

How fresh the data is, and whether to retry shortly.
How confident the platform is in the answer.
Which upstream sources the answer was synthesized from.
Whether the response is fit for autonomous use, or whether a human or fallback path should review it first.

The envelope is purely additive — SDKs and dashboards that ignore _agentic keep working unchanged. For the full field reference see Response envelope; for the freshness and quality-gate enums see Freshness & staleness. This page is about consuming the signal.

Wire shape (recap)

"meta": {
  "_agentic": {
    "schema_version": "1.0.0",
    "freshness": { "status": "realtime", "should_retry": false, "update_cadence_seconds": 300 },
    "confidence": 0.92,
    "sources": ["timescaledb", "archive_node"],
    "quality_gate": { "verdict": "pass", "reason": "", "degraded_fields": [] }
  }
}

Two headers mirror the body so middleware, HEAD requests, and cheap routing can act without parsing JSON:

X-Schema-Version — mirrors _agentic.schema_version (currently 1.0.0).
X-Quality-Gate — mirrors _agentic.quality_gate.verdict (pass / warn / fail).

How to consume it, by consumer type

Consumer	Reads	Recommended use
Dashboard / human	`meta` for cache-age, `data` for the payload	Ignore `_agentic`; render human-readable freshness from `computed_at`.
Backtest / batch ETL	`freshness.computed_at`, `confidence`	Pin `computed_at` as the cache key; drop rows where `confidence < 0.50` from training data.
Realtime alerting	`X-Quality-Gate` header	Route `pass` to the rule engine; route `warn` to a human inbox; drop `fail`.
Autonomous agent	full `_agentic` block	Honor `should_retry` + `retry_after_seconds` for backoff; treat `verdict == fail` as a hard gate; log `degraded_fields` to the observation trail.

Agent rules of thumb

Back off correctly. When freshness.should_retry is true, retry after retry_after_seconds if present, otherwise back off using update_cadence_seconds as the floor.
Treat fail as a hard gate. A quality_gate.verdict of fail means do not act unsupervised — fall back to a cached or alternative source, or escalate to a human.
Inspect degraded_fields. When non-empty, the listed JSON paths inside data were degraded, missing, or fell back to a less-authoritative source. For example, an oracle handler may emit degraded_fields: ["per_aggregator_breakdown"] when aggregator introspection timed out but the headline price held.
Refuse truncated payloads. If _agentic.truncated is true, the response was clipped at an output cap — do not act on it; re-request with a narrower query.

Trust framing

The same signal, framed for an institutional evaluator, lives at Trust → Freshness & quality: every response states how fresh and how trustworthy its numbers are, as a first-class field rather than a footnote.

​Wire shape (recap)

​How to consume it, by consumer type

​Agent rules of thumb

​Trust framing

Wire shape (recap)

How to consume it, by consumer type

Agent rules of thumb

Trust framing