@mastra/core/dist/docs/references/reference-editor-versioning.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Versioning

Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations. Code-backed agent overrides use deterministic files and Git history.

See [Editor versioning](https://mastra.ai/docs/editor/overview) for release and experimentation patterns.

## Database lifecycle

The resource record stores an `activeVersionId`. Individual snapshots don't store a lifecycle status.

| Term       | Meaning                                                                                      |
| ---------- | -------------------------------------------------------------------------------------------- |
| Latest     | The most recently created configuration snapshot                                             |
| Published  | The snapshot selected by `activeVersionId`                                                   |
| Draft      | The latest snapshot when it differs from `activeVersionId`, or when no active version exists |
| Historical | Any other retained snapshot                                                                  |

Saving changed snapshot fields creates a new latest version. Saving identical snapshot fields or changing metadata alone doesn't create a version.

If an active version exists, creating a draft doesn't change the version handling published requests. Publishing updates `activeVersionId`. Restoring a historical version copies its configuration into a new inactive draft.

The direct namespace methods and REST APIs differ in one important way. `editor.prompt.update()` creates an inactive draft. `editor.agent.update()` creates a version and immediately assigns it to `activeVersionId`. The stored-agent REST `PATCH` route creates an inactive draft unless `autoPublish` is enabled.

When a generic stored resource has no active version, published resolution can fall back to the latest snapshot. For a code-defined agent override, requesting `status: 'published'` without an active override returns the original code agent.

## Code source

With `source: 'code'`, active agent overrides are serialized as deterministic JSON under `<codePath>/agents/<encodedAgentId>.json`. The default `codePath` is `./mastra/editor`.

The initial agent is published to create the file. Later server updates create a draft by default and write the file when that version becomes active. Git versions are read-only in Studio and use the commit message as their change message. The default history scan reads up to 50 recent commits and skips consecutive commits whose parsed JSON snapshot is unchanged.

See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for source options.

## Select an agent version

Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/editor/overview) for a TypeScript example.

With the default server prefix, pass selectors as query parameters under `/api`:

```bash
# Published version
curl http://localhost:4111/api/agents/support-agent

# Latest draft
curl http://localhost:4111/api/agents/support-agent?status=draft

# Exact version
curl http://localhost:4111/api/agents/support-agent?versionId=abc-123
```

See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for Client SDK and React SDK selectors.

## Sub-agent versioning

Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:

1. `Mastra` instance `versions`: Defaults for every invocation
2. Server request-body `versions`: Per-request values added to request context
3. Direct `generate()` or `stream()` `versions`: Per-invocation values

Entries merge by agent ID. For the same ID, precedence is **direct invocation > request body or existing request context > Mastra instance default**.

Set defaults on the Mastra instance:

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: { supervisor, researchAgent, writerAgent },
  editor: new MastraEditor(),
  versions: {
    agents: {
      'research-agent': { status: 'published' },
      'writer-agent': { versionId: 'abc-123' },
    },
  },
})
```

Override one sub-agent for a direct invocation:

```typescript
const result = await supervisor.generate('Research and write about AI safety', {
  versions: {
    agents: {
      'research-agent': { status: 'draft' },
    },
  },
})
```

Or pass selectors in the server request body:

```bash
curl -X POST http://localhost:4111/api/agents/supervisor/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Research AI safety" }],
    "versions": {
      "agents": {
        "research-agent": { "status": "draft" }
      }
    }
  }'
```

If Editor isn't configured or a version can't be resolved, Mastra logs a warning and uses the code-defined sub-agent.

## Stored-agent REST API

The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.

| Method   | Path                                           | Description                                                          |
| -------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| `GET`    | `/api/stored/agents`                           | List stored agents                                                   |
| `POST`   | `/api/stored/agents`                           | Create a stored agent                                                |
| `GET`    | `/api/stored/agents/:storedAgentId`            | Get a stored agent                                                   |
| `PATCH`  | `/api/stored/agents/:storedAgentId`            | Update a stored agent                                                |
| `DELETE` | `/api/stored/agents/:storedAgentId`            | Delete a stored agent                                                |
| `GET`    | `/api/stored/agents/:storedAgentId/dependents` | List readable dependents and count hidden cross-workspace references |
| `POST`   | `/api/stored/agents/:storedAgentId/export`     | Export the allowed override fields as deterministic JSON             |

The dependents response lists caller-readable agents by `id` and `name`. Its `hiddenCount` field counts cross-workspace references that the caller can't read, but only when the target agent is public.

Version-management routes are nested under `/api/stored/agents/:storedAgentId/versions`. See [version management](https://mastra.ai/reference/client-js/agents) for operations and Client SDK methods.

The Client SDK exposes `listStoredAgents()`, `createStoredAgent()`, and `getStoredAgent()`. The resource returned by `getStoredAgent(id)` includes methods for updates, deletion, dependents, export, and version management.