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

# Version management

## 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:

```mermaid theme={null}
flowchart LR
    A["@graphysdk/core"] -->|defines| B["GraphConfig"]
    B -->|sent by| C["@graphysdk/agents-sdk"]
    C -->|over HTTP| D["Agents API"]
    D -->|returns| B
    B -->|rendered by| E["Graph component"]
```

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

<Note>The API is on `v0`. Breaking changes may occur. Use the TypeScript SDK for the most stable integration.</Note>

| API version | Status                                             |
| ----------- | -------------------------------------------------- |
| `v0`        | Active, pre-stable. May change.                    |
| `v1`        | Planned. Stable, backward-compatible within major. |

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:

<CodeGroup>
  ```bash npm theme={null}
  npm install @graphysdk/agents-sdk@latest @graphysdk/core@latest
  ```

  ```bash yarn theme={null}
  yarn add @graphysdk/agents-sdk@latest @graphysdk/core@latest
  ```

  ```bash pnpm theme={null}
  pnpm add @graphysdk/agents-sdk@latest @graphysdk/core@latest
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## 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
```

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.