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.
| API version | Status |
|---|
v0 | Active, pre-stable. May change. |
v1 | Planned. Stable, backward-compatible within major. |
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:
npm install @graphysdk/agents-sdk@latest @graphysdk/core@latest
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?
| Change | What bumps | API version change? |
|---|
| New chart type or config option | @graphysdk/core minor | No |
New optional field on GraphConfig | @graphysdk/core minor | No |
Breaking GraphConfig change | @graphysdk/core major | Yes (major bump) |
| New SSE event type | Backwards-compatible addition | No |
| New endpoint added | Backwards-compatible addition | No |
| Endpoint renamed or removed | API major | Yes (major bump) |
| Auth mechanism change | API major | Yes (major bump) |
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:
https://agents.graphy.dev/api/v0/generate
