> ## 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 (Identity)

Use this API to update identity fields on the root agent document. **No new version is created.** Works for both custom and built-in agents, though built-in agents only support updating `enabled`.

For behavioral changes (instructions, context gathering, execution, post-processing, scope), use [Update Agent Version](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md) instead, which creates a new version.

# Endpoint

`POST https://api.velt.dev/v2/agents/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*

Min 1 char. Agent ID to update (custom or built-in).

**name** `string`

Min 1 char. Agent display name. Not supported for built-in agents.

**description** `string`

Human-readable description. Not supported for built-in agents.

**enabled** `boolean`

Whether the agent is active.

Provide at least one of `name`, `description`, or `enabled`. This is not schema-enforced — a request without any of them succeeds as a no-op for custom agents, and returns `INVALID_ARGUMENT` for built-in agents (which require `enabled`).

## **Example Requests**

#### 1. Rename an agent

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "name": "Updated Brand Checker",
    "description": "Now also checks footer typography"
  }
}
```

#### 2. Disable an agent

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "enabled": false
  }
}
```

#### 3. Enable a built-in agent

```JSON theme={null}
{
  "data": {
    "agentId": "spell-check",
    "enabled": true
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent updated successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `data.agentId` | string | The ID of the updated agent |

#### Failure Response

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

**Errors:**

* `INVALID_ARGUMENT`: missing `agentId`, empty `name`, or updating a built-in agent without the `enabled` field. Built-in agents support `enabled` only, and a `name` or `description` sent alongside it is silently ignored.
* `NOT_FOUND`: the workspace store database could not be resolved.
* `INTERNAL`: the agent does not exist.

> [!NOTE]
>
> Updating an agent that does not exist surfaces as `INTERNAL`, not `NOT_FOUND`. Check existence with [Get Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/get.md) if you need to distinguish a missing agent from a genuine server error.
>
> This endpoint also ignores fields it does not own. Behavioral fields such as `instructions` or `execution` sent here are silently dropped and the call still returns `200`; use [Update Agent Version](https://velt.dev/docs/api-reference/rest-apis/v2/agents/version/update.md) for those.

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Agent updated successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}
```


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