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

# Update Agent Version (Behavioral)

Use this API to update behavioral/version fields on a custom agent. Creates a new version `N+1` in the versions subcollection, updates the `version` pointer on the root document, and bumps `updatedAt`.

In-flight executions stay pinned to whatever version they started on — the update only affects future executions.

The schema uses `.passthrough()` so additional behavioral fields are forwarded. Deep validation happens in the service layer via `updateCustomAgentConfigSchema`.

**Custom agents only.** Use [Update Agent](/api-reference/rest-apis/v2/agents/update) for identity edits on built-in agents.

# 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](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      Min 1 char. 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).
    </ParamField>

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

    <ParamField body="execution" type="object">
      Execution config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-execution).
    </ParamField>

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

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

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

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

    <ParamField body="setup" type="object">
      Setup assistant metadata. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-setup).
    </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 },
      "matchAndMerge": { "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 execution

```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:** `NOT_FOUND` (agent does not exist) / `INVALID_ARGUMENT` (validation failure or attempting to update a built-in agent's behavior).

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