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.

v1 is deprecated. v2 is the current major version and the only one new integrations should target. This page covers the high-level changes; for the exact shape of any single endpoint, the API Reference is the source of truth, and the deprecation response headers (below) point you at the per-endpoint migration notes.
There is no field-by-field rename table here on purpose. Where a v1 endpoint has a v2 successor, the endpoint reference documents its current request and response shape, and the Link deprecation header on the old endpoint names the successor. Trust those, not a copied-out mapping.

​
The base-path change

The path-level major version lives in the URL. v2 endpoints are served under the /v2/ prefix: 
https://api.alterscope.org/v2/<resource>
Most v1 data endpoints have already been retired in favour of their /v2/ equivalent. For example, the legacy POST /v1/yield/portfolio/analyze was removed and its successor is POST /v2/yield/portfolio/analyze — the request and response schemas are unchanged from the v1 surface, so for that endpoint the migration is a base-path swap and nothing more. 
curl -H "Authorization: Bearer sk_live_xxx" \
     "https://api.alterscope.org/v2/yield/opportunities?limit=10"
Not every endpoint is a clean swap. Some v2 successors changed paths or parameters; read the deprecation headers and the endpoint reference before assuming a one-to-one mapping.

​
The response envelope

Every /v2/* response uses the standard envelope: 
{
  "data": { },
  "meta": { },
  "error": null
}
  • data holds the response payload (an object or an array).
  • meta holds pagination and metadata.
  • error is null on success, or an error object on failure.
A subset of /v2/* endpoints additionally populate the agentic extension at meta._agentic — machine-readable freshness, provenance (sources), confidence, and a quality_gate verdict, alongside the envelope schema_version. The rollout of _agentic across the API is in progress; endpoints that don’t yet emit it return the base { data, meta, error } envelope. Both shapes are valid. See Versioning for how the envelope schema_version is governed.
The envelope schema_version (at meta._agentic.schema_version, mirrored by the X-Schema-Version response header) is versioned independently of the path-level major. A major bump on schema_version always coincides with a new path-level major. Read Versioning for the full policy.

​
Authentication is unchanged

Auth is identical across versions. Send your API key as a bearer token: 
Authorization: Bearer sk_live_xxx
This is the only form that authenticates an HTTP request. Browser WebSocket clients, which can’t set custom headers, pass the key via the ?token= query parameter on connect. See Authentication for key lifecycle, scopes, and rotation.

​
Detecting deprecation

You don’t have to guess which endpoints are on their way out. Every response on a deprecated endpoint carries the RFC 8594 header triple: 
Deprecation: true
Sunset: <RFC 1123 date>
Link: <successor-url>; rel="deprecation"
  • Deprecation: true flags the response as coming from a deprecated endpoint.
  • Sunset: carries the removal date.
  • Link: (with rel="deprecation" or rel="successor-version") points at the migration notes or the successor endpoint.
Inspect these headers in your client to find what needs migrating and by when. In the TypeScript (@alterscope/sdk) and Python (alterscope, Beta) SDKs, the corresponding request methods and types are also marked @deprecated, so your editor and compiler surface the hint at build time. If you generate a client from the OpenAPI spec instead, read the headers directly. After the sunset date a removed endpoint returns 410 Gone. The full deprecation timeline — announcement, header roll-out, the 180-day window, and removal — is documented in Versioning.

​
Checklist

Moving to v2

  1. Repoint your base path to /v2/.
  2. Read data, meta, and error from the standard envelope; treat meta._agentic as present-or-absent per endpoint.
  3. Keep sending Authorization: Bearer sk_live_... — auth is unchanged.
  4. Watch for Deprecation / Sunset / Link headers and follow the successor each one names.
  5. Confirm each endpoint’s current shape against the API Reference.

​
Cross-references

  • Versioning — what is breaking, what is not, and the deprecation window.
  • API Reference — current request and response shapes.
  • Authentication — keys, scopes, rotation.
  • Errors — the error object and status codes.