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

Use this API to update identity fields (`name`, `description`, `enabled`) on the root agent document. **No new version is created.** Use [Update Agent Version](/api-reference/rest-apis/v2/agents/version/update) for behavioral edits.

Works for both custom and built-in agents, but built-in agents only support updating `enabled`. 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. New display name. Not allowed for built-in agents.
    </ParamField>

    <ParamField body="description" type="string">
      New human-readable description. Not allowed 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 a custom 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` (sending `name` or `description` for a built-in agent — only `enabled` is allowed) / `NOT_FOUND` (agent does not exist).

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