> ## Documentation Index
> Fetch the complete documentation index at: https://velt-raghul-agents-doc-latest.mintlify.site/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](/api-reference/rest-apis/v2/agents/version/update) instead, which creates a new version.

Server-managed fields (`id`, `apiKey`, `managedBy`, `metadata`, `version`, `createdAt`, `updatedAt`) cannot be set through this endpoint.

# Endpoint

`POST https://api.velt.dev/v2/agents/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. Agent ID to update (custom or built-in).
    </ParamField>

    <ParamField body="name" type="string">
      Min 1 char. Agent display name. Not supported for built-in agents.
    </ParamField>

    <ParamField body="description" type="string">
      Human-readable description. Not supported for built-in agents.
    </ParamField>

    <ParamField body="enabled" type="boolean">
      Whether the agent is active.
    </ParamField>
  </Expandable>
</ParamField>

At least one of `name`, `description`, or `enabled` should be provided.

## **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 sending `name`/`description` for a built-in agent — built-in agents only support the `enabled` field) / `NOT_FOUND` (agent does not exist).

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