> ## 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.

# Delete Agent

Use this API to delete a custom agent configuration and all of its versions.

**Group cleanup:** Before the agent document and its versions subcollection are deleted, the `agentId` is first removed from the `agentIds` array of every agent group it belongs to. If cleanup fails, the delete is aborted and the agent is left intact, so the call can be safely retried. Groups themselves are never deleted, even if they become empty.

# Endpoint

`POST https://api.velt.dev/v2/agents/delete`

# 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>
      Min 1 char. Agent ID to delete.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

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

# Response

#### Success Response

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

| Field          | Type   | Description                          |
| -------------- | ------ | ------------------------------------ |
| `data.agentId` | string | The `agentId` you sent, echoed back. |

<Note>
  **Delete is idempotent.** Deleting an agent that does not exist (or was already deleted) returns `200 success` with the `agentId` echoed back, not an error. Do not rely on the response to tell you whether the agent existed; call [Get Agent](/docs/api-reference/rest-apis/v2/agents/get) first if you need to know.
</Note>

#### Failure Response

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

**Errors:** `INVALID_ARGUMENT` (missing or empty `agentId`) / `NOT_FOUND` (the workspace store database could not be resolved) / `INTERNAL` (group cleanup failed, in which case the agent is left intact and the call can be safely retried).

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