> ## 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.

# Migrating from v1 to v2

> What changed between the v1 and v2 Alterscope Developer API, and how to move your integration over.

`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](/api-reference/overview)
is the source of truth, and the deprecation response headers (below) point you
at the per-endpoint migration notes.

<Note>
  There is no field-by-field rename table here on purpose. Where a v1 endpoint
  has a v2 successor, the [endpoint reference](/api-reference/overview) 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.
</Note>

## 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.

<CodeGroup>
  ```bash v2 theme={null}
  curl -H "Authorization: Bearer sk_live_xxx" \
       "https://api.alterscope.org/v2/yield/opportunities?limit=10"
  ```

  ```bash v1 (deprecated) theme={null}
  # Old base path — being retired. Move to /v2.
  curl -H "Authorization: Bearer sk_live_xxx" \
       "https://api.alterscope.org/v1/yield/opportunities?limit=10"
  ```
</CodeGroup>

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:

```json theme={null}
{
  "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](/develop/get-started/errors)
  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](/api-reference/versioning) for
how the envelope `schema_version` is governed.

<Note>
  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](/api-reference/versioning) for the full policy.
</Note>

## Authentication is unchanged

Auth is identical across versions. Send your API key as a bearer token:

```http theme={null}
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](/develop/get-started/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](/api-reference/overview) 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](/api-reference/versioning#deprecation-window).

## Checklist

<Card title="Moving to v2" icon="list-check">
  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](/api-reference/overview).
</Card>

## Cross-references

* [Versioning](/api-reference/versioning) — what is breaking, what is not, and the deprecation window.
* [API Reference](/api-reference/overview) — current request and response shapes.
* [Authentication](/develop/get-started/authentication) — keys, scopes, rotation.
* [Errors](/develop/get-started/errors) — the error object and status codes.