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 entire system: Since the Agents API generates GraphConfig, breaking changes to its shape require a new API major version. All SDK packages and the API share the same major version number: SDK 1.x works with API v1, SDK 2.x works with API v2, and so on. Non-breaking additions to GraphConfig (new optional fields, new chart types) ship as @graphysdk/core 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 packages compatible

@graphysdk/agents-sdk declares @graphysdk/core as a peer dependency. Both packages must use the same major version for the GraphConfig type to match across the SDK and your rendering layer. When upgrading, always update both:
Using mismatched versions of @graphysdk/agents-sdk and @graphysdk/core may cause type errors at compile time or unexpected behaviour at runtime. Always keep them in sync.

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