> ## 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](/docs/api-reference/rest-apis/v2/agents/get) first, apply your change to the full nested object, and send that. Read the credential warning below before you do.
</Warning>

<Warning>
  **Never send a redacted secret back.** [Get Agent](/docs/api-reference/rest-apis/v2/agents/get) 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.
</Warning>

# Endpoint

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

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/docs/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      Custom agent ID.
    </ParamField>

    <ParamField body="rawInstructions" type="string">
      Original user-provided instructions.
    </ParamField>

    <ParamField body="instructions" type="string">
      Processed/enhanced instructions.
    </ParamField>

    <ParamField body="phaseTimeoutMs" type="number">
      Per-phase timeout in milliseconds. Positive integer, no upper bound. Omit to use the platform default.
    </ParamField>

    <ParamField body="metadata" type="object">
      Arbitrary client metadata. Replaces the stored object rather than merging into it.
    </ParamField>

    <ParamField body="contextGathering" type="object">
      Context gathering config. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create#context-gathering-strategies).
    </ParamField>

    <ParamField body="execution" type="object">
      Execution config, including `executionStrategy`, the strict `knowledge` (Memory-RAG) block, and `mcpServers` for the `"mcp-tools"` strategy. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create#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](/docs/api-reference/rest-apis/v2/agents/get) response stores that string as the credential.
    </ParamField>

    <ParamField body="response" type="object">
      Response formatting config. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create).
    </ParamField>

    <ParamField body="postProcess" type="object">
      Post-processing pipeline config. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create).
    </ParamField>

    <ParamField body="input" type="object">
      Input declaration config. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create).
    </ParamField>

    <ParamField body="scope" type="object">
      Scope and targeting config. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create).
    </ParamField>

    <ParamField body="setup" type="object">
      Setup assistant metadata. Same shape as [Create Agent](/docs/api-reference/rest-apis/v2/agents/create).
    </ParamField>
  </Expandable>
</ParamField>

## **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"]
      }
    }
  }
}
```

# 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, 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.
</Note>

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