Skip to main content

​
What the API version covers

The API uses URL-path versioning (/api/v0/, /api/v1/, etc.). Specifically, the API version covers:
  • Endpoints - available routes and their HTTP methods
  • SSE envelope - event types (progress, complete, error) and their shapes
  • Authentication - how API keys are passed and validated
  • Error codes - error response structure and codes
  • Request envelope - top-level request fields (userPrompt, metadata)
  • GraphConfig schema - breaking changes to GraphConfig trigger a new API major version

​
GraphConfig is the data contract

GraphConfig is the central type that flows through the Agents system. The wire type ships in @graphysdk/agents-sdk: Since the Agents API generates GraphConfig, breaking changes to its shape require a new API major version. Keep the TypeScript SDK on a compatible major with the API path you call (today: SDK 1.x with API v0). Non-breaking additions to the wire GraphConfig (new optional fields, new chart types) ship as @graphysdk/agents-sdk minor releases and do not require an API version change.

​
Current version

The API is on v0. Breaking changes may occur. Use the TypeScript SDK for the most stable integration.
When v1 ships, the same guarantees as the SDK packages apply: no breaking changes within a major version, with a deprecation cycle before removal.

​
Keeping the SDK up to date

Install or upgrade the Agents client alone:
Rendering is separate from the Agents client — use @graphysdk/react when you want to display charts.

​
When does what change?

​
REST API consumers

If you integrate directly with the REST API (without the TypeScript SDK), pin to a specific API version in your URLs and test before upgrading:
The TypeScript SDK handles API version targeting internally. When a new API version is available, updating the SDK is enough. You do not need to change URLs in your code.