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

# API stability

> Understand API versions, compatible changes, and SDK upgrades.

Context.dev exposes three related contracts. Keep them separate when you build and upgrade an integration.

| Surface       | Source of truth                                          | What to pin or verify                                                            |
| ------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- |
| HTTPS API     | The versioned path and [OpenAPI document](/openapi.json) | Base path, method, parameters, status codes, and response schema                 |
| API reference | Generated from the OpenAPI document                      | Confirm the page references the operation you call                               |
| Language SDK  | The package version installed in your project            | Generated method names, request models, retry defaults, and runtime requirements |

The current base URL is:

```text theme={null}
https://api.context.dev/v1
```

## What can change within v1

Clients should tolerate compatible additions and implementation changes, including:

* New endpoints and optional request parameters.
* New optional response fields.
* New enum values where the reference describes a value set as extensible.
* Bug fixes that bring behavior back to the documented contract.
* Model, cache, proxy, and infrastructure changes that preserve the request and response contract.

Parse the fields your application needs and ignore unknown response keys. Do not use exhaustive switches for a value set documented as extensible without a default branch.

## What Context.dev treats as breaking

These changes require a new version or a communicated migration path:

* Removing or renaming an endpoint, request parameter, or response field.
* Changing the type or documented meaning of an existing field.
* Making an optional parameter required.
* Rejecting an input that the published contract previously accepted.
* Changing a documented status code or stable `error_code` for the same condition.

Breaking changes are announced in the [changelog](/changelog). The current deprecation policy is to keep a deprecated surface available for at least 90 days after its announcement. Contractual support windows can differ for Enterprise agreements.

## SDKs can lag the server contract

SDKs are generated from API descriptions, but package publication is a separate release event. A published package can lag the current server contract or model a union incorrectly.

As verified on September 4, 2026:

* The old unversioned Go SDK `v1.5.0` exposes a legacy GET Brand request and cannot express the current discriminated `POST /brand/retrieve` body. Check the current `/v2` module when upgrading.
* The PHP SDK `v2.14.0` Brand convenience method requires fields from mutually exclusive lookup variants.

The [SDK guide](/sdks) lists language-specific installation and compatibility details. Before using an SDK method copied from documentation:

1. Check the package version installed in the project.
2. Inspect the generated signature or type definition.
3. Compare the outgoing request with the current API reference.
4. Use raw HTTPS when the package cannot represent the public contract.

This limitation applies to the affected generated client method, not to the HTTPS API itself.

## Data can change

For extraction, product, and classification operations, distinguish output shape from output value:

* A successful structured-extraction response follows the requested JSON Schema, but the extracted values can change as source pages or models change.
* `factCheck=true` restricts structured extraction to page-supported facts; it does not make a website an authoritative registry.
* Classification returns codes from the selected taxonomy, but the selected candidates and confidence can change as company evidence changes.
* Brand assets and metadata can change when sites, source data, or cache state change.

Validate structured output in your application and test the semantic behavior your product depends on. A type check alone does not prove extraction quality.

## Upgrade safely

* Pin a compatible SDK version in production.
* Read SDK release notes and the [Context.dev changelog](/changelog) before upgrading.
* Run a recorded success case and representative failure cases after an upgrade.
* Keep raw HTTPS contract tests for critical operations so SDK serialization regressions are visible.
* Monitor the [status page](https://status.context.dev) for incidents rather than treating runtime failures as contract changes.

For a question about a specific compatibility window, contact [support@context.dev](mailto:support@context.dev).