> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-baseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API versions

> Select REST v2 and migrate clients without changing their API keys.

The AI Baseline API currently supports **REST v2**. Select the contract in the URL:

```text theme={null}
https://api.ai-baseline.dev/{org}/{base}/v2
```

For AI Baseline S\&P 500, use `https://api.ai-baseline.dev/baseline/sandp500/v2`.
Append `/query`, `/metadata-filters` or `/corpus-overview`. Authenticate with your
existing `X-API-Key`. The URL selects the version; no version header is required.
The published OpenAPI identifies this contract as `2.0.0`, independently of
application images, knowledge-base releases and MCP protocol versions.

## Existing integrations

The previous `https://api.ai-baseline.dev/baseline/sandp500` base URL remains a
**pinned alias of v2**. It uses the same requests, responses, authentication and
quota, without redirects. To migrate, append `/v2` to your configured base URL:

```python theme={null}
# Previous URL remains supported.
api_base = "https://api.ai-baseline.dev/baseline/sandp500"
# Preferred URL explicitly selects v2.
api_base = "https://api.ai-baseline.dev/baseline/sandp500/v2"
response = requests.post(f"{api_base}/query", headers={"X-API-Key": api_key},
                         json={"query": "Apple financial results", "mode": "research"})
```

The quickstart, API reference, OpenWebUI example and public research notebook
use the explicit v2 base. Existing native-domain `/v2/{deployment}` integrations
also remain on v2. Private client configurations are not automatically edited.

Unsupported versions such as `/baseline/sandp500/v3/query` return HTTP `404`:

```json theme={null}
{"error_msg": "404 Route Not Found"}
```

There is no fallback to a different version. Gateway errors can use a different
JSON shape from application errors; see [Errors](https://docs.ai-baseline.com/guides/errors.md).

## Compatible changes and support

Optional additive fields and operations, retrieval improvements and bug fixes
can ship within v2. Clients should ignore unknown response fields. Removing or
renaming fields, changing their types or meaning, requiring new request inputs,
or breaking documented authentication/error handling requires a new major.

A replacement major will have its own OpenAPI and migration instructions and
will coexist with the previous supported major. Deprecation and any removal date
will be announced in these docs and release notes at least **90 days before
removal**, naming affected versioned and alias URLs. No retirement is scheduled.
An unversioned v2 alias will never silently switch to a newer major.

### Example of a future breaking change

A planned response simplification may remove duplicate
`agent_context.content_parts` and introduce opt-in inline images. **That change
is not available yet.** V2 retains its current `agent_context.text`,
`content_parts` and image/reference behavior. Existing clients continue using v2
unchanged. A future client would first adopt the new text/image parser, then
select the separately documented v3 URL after release. Calling `/v3` today
returns 404.

## MCP connections

Claude, ChatGPT and other hosted MCP consumers keep using
`https://mcp.ai-baseline.dev/{org}/{base}`. Do not append `/v2` to an MCP URL.
REST majors and MCP protocol negotiation are separate. Tool names, arguments,
outputs and authentication/resource URLs receive their own compatibility review;
a new REST version does not change your MCP connector.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.