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

# Update Agent Version

Use this API to update behavioral/version fields. This **creates a new version N+1** in the versions subcollection and bumps the `version` pointer on the root document. Only supported for custom agents.

In-flight executions stay pinned to whatever version they started on, so updating a version never disturbs a running execution.

The schema uses `.passthrough()`, so additional behavioral fields are forwarded to the service layer.

> [!WARNING]
>
> **The merge is one level deep.** Each top-level block you send (`contextGathering`, `execution`, `response`, `postProcess`, `input`, `scope`, `setup`) is merged onto its stored counterpart, but anything nested inside is **replaced wholesale**, not merged.
>
> So sending `{ "scope": { "crossPage": { "enabled": false, "targetProperty": "brandConsistency", "pageDiscovery": "auto" } } }` does not just flip `enabled`. It replaces the whole `crossPage` object, silently discarding the stored `pages` list and `sourceOfTruthKnowledgeSourceId`, and returns `200`. Nothing warns you. The same applies to `execution.mcpServers`, `input.userContextFields`, and `contextGathering.strategyOptions`: send the complete nested object every time, not just the keys you want to change.
>
> Drop a required key and you get the louder failure instead: `{ "scope": { "crossPage": { "enabled": false } } }` is rejected with `INVALID_ARGUMENT`, because `targetProperty` and `pageDiscovery` are required whenever `crossPage` is present.
>
> Fetch the current config with [Get Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/get.md) first, apply your change to the full nested object, and send that. Read the credential warning below before you do.

> [!WARNING]
>
> **Never send a redacted secret back.** [Get Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/get.md) returns auth secrets as the literal string `"__redacted__"`. This endpoint has no special handling for that value, so a fetch-modify-send round trip stores `"__redacted__"` as the real credential and the server starts failing authentication at execution time, not at update time.
>
> To change something else on an agent that has stored secrets, either omit `execution.mcpServers` and `contextGathering.strategyOptions` from your patch entirely, or re-send every object with its real plaintext secret. Rotating a secret is the same operation: send the new plaintext value.

# Endpoint

`POST https://api.velt.dev/v2/agents/version/update`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**agentId** `string` *required*

Custom agent ID.

**rawInstructions** `string`

Original user-provided instructions.

**instructions** `string`

Processed/enhanced instructions.

**phaseTimeoutMs** `number`

Per-phase timeout in milliseconds. Positive integer, no upper bound. Omit to use the platform default.

**metadata** `object`

Arbitrary client metadata. Replaces the stored object rather than merging into it.

**contextGathering** `object`

Context gathering config. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md#context-gathering-strategies).

**execution** `object`

Execution config, including `executionStrategy`, the strict `knowledge` (Memory-RAG) block, and `mcpServers` for the `"mcp-tools"` strategy. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md#mcp-servers-mcp-tools-strategy).

Rotate an MCP or REST auth secret by sending the new plaintext value here. Because `mcpServers` is an array, sending it replaces the stored array in full: a server object sent without its `auth` block **loses** the stored secret. To keep existing secrets, either omit `mcpServers` entirely or re-send every server object with its real plaintext secret. Re-sending the `"__redacted__"` placeholder from a [Get Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/get.md) response stores that string as the credential.

**response** `object`

Response formatting config. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md).

**postProcess** `object`

Post-processing pipeline config. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md), including `findingEnrichment.commentFormat` ([Comment format](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md#comment-format)).

**input** `object`

Input declaration config. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md).

**scope** `object`

Scope and targeting config. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md).

**setup** `object`

Setup assistant metadata. Same shape as [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md).

## **Example Requests**

#### 1. Update instructions and post-processing

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.",
    "postProcess": {
      "guardrails": { "enabled": true },
      "deletePreviousSuggestions": { "enabled": true }
    }
  }
}
```

#### 2. Update context gathering strategies

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "contextGathering": {
      "strategies": ["web-page-text", "web-page-html", "web-page-screenshot"]
    }
  }
}
```

#### 3. Enable cross-page via scope

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "scope": {
      "crossPage": {
        "enabled": true,
        "targetProperty": "brandConsistency",
        "pageDiscovery": "manual",
        "pages": ["https://example.com", "https://example.com/about"]
      }
    }
  }
}
```

#### 4. Switch to the plain comment format

The agent's next runs post comments with a bold title, a detail line, and the suggestion, with no `Suggestion:` label. The other `postProcess` keys you stored are kept.

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "postProcess": {
      "findingEnrichment": { "commentFormat": "plain" }
    }
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `data.version` | number | New version number after the update |

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

**Errors:** `INVALID_ARGUMENT` (validation failure, including a nested block that lost required fields to the one-level merge, a `userContextFields` id that is a reserved run-scope or run-control key, or blanking `instructions` on an agent whose effective `executionStrategy` still requires a prompt) / `NOT_FOUND` (agent does not exist).

> [!NOTE]
>
> `instructions` is re-validated against the **merged** result, not against your patch alone. The merged `instructions` must be non-empty whenever the merged `executionStrategy` is `"ai"`, `"service+ai"`, `"stagehand-agent"`, or `"mcp-tools"`. Whitespace-only counts as empty.
>
> So clearing `instructions` on an existing AI agent is rejected, even though the field is optional on this endpoint.

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent version created successfully",
    "data": {
      "version": 4
    }
  }
}
```


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