> ## 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 Agents system. The wire type ships in `@graphysdk/agents-sdk`:

```mermaid theme={null}
flowchart LR
    A["@graphysdk/agents-sdk"] -->|defines wire| B["GraphConfig"]
    B -->|sent by| C["GraphyAiSdk"]
    C -->|over HTTP| D["Agents API"]
    D -->|returns| B
    B -->|optional render| E["@graphysdk/react"]
```

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

<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 the SDK up to date

Install or upgrade the Agents client alone:

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

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

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

Rendering is separate from the Agents client — use `@graphysdk/react` when you want to display charts.

## When does what change?

| Change | What bumps | API version change? |
| - | - | - |
| New chart type or config option | `@graphysdk/agents-sdk` minor | No |
| New optional field on `GraphConfig` | `@graphysdk/agents-sdk` minor | No |
| Breaking `GraphConfig` change | `@graphysdk/agents-sdk` 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.