Skip to main content

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.

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:
  1. How fresh the data is, and whether to retry shortly.
  2. How confident the platform is in the answer.
  3. Which upstream sources the answer was synthesized from.
  4. 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

ConsumerReadsRecommended use
Dashboard / humanmeta for cache-age, data for the payloadIgnore _agentic; render human-readable freshness from computed_at.
Backtest / batch ETLfreshness.computed_at, confidencePin computed_at as the cache key; drop rows where confidence < 0.50 from training data.
Realtime alertingX-Quality-Gate headerRoute pass to the rule engine; route warn to a human inbox; drop fail.
Autonomous agentfull _agentic blockHonor 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.