Skip to main content
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.