Skip to main content
Context.dev exposes three related contracts. Keep them separate when you build and upgrade an integration. The current base URL is:

​
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. 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 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 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 for incidents rather than treating runtime failures as contract changes.
For a question about a specific compatibility window, contact [email protected].

​
September 2026 timeout migration

Timeout-enabled endpoints now use timeoutOpts with milliseconds and a fail or return-partial behavior. Legacy timeoutMS remains accepted with fail semantics. On product catalog extraction, explicit deadlines previously implied partial success. They now fail with an unbilled 408 unless partial mode is explicitly selected. See the migration guide for the replacement request and completion markers. SDK 2.14.0 typed helpers can lag this contract; the guides show supported low-level calls.