> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DELETE /agents/{id} — permanently remove an agent

> Permanently delete an agent and immediately disable its proxy URL. Past sessions are preserved for compliance audit. This action cannot be undone.

Permanently deletes an agent from your account. The agent's proxy URL stops accepting new requests immediately. Past sessions tied to this agent are preserved in the database for compliance audit purposes but will no longer appear in the agent's session listing.

<Warning>
  This action cannot be undone. There is no soft delete or restore operation today. A 30-day soft-delete with restore is on the roadmap.
</Warning>

## Endpoint

```
DELETE /api/v1/agents/{agent_id}
```

Requires `masker_session` authentication. The signed-in user must be an account admin.

## Path parameters

<ParamField path="agent_id" type="string" required>
  The agent's ID in `agt_*` ULID format, e.g. `agt_01HYZ...`.
</ParamField>

## Response

Returns `204 No Content` on success with no response body.

## What happens on delete

1. The agent row is removed from the database.
2. In-flight requests on the agent's proxy URL complete normally; new requests immediately receive `404`.
3. Past sessions are preserved with a back-reference to the deleted agent's ID. They remain accessible via [GET /sessions](/api-reference/sessions/list-sessions) and individual session detail endpoints.
4. The vault is **not** purged. Tokens issued by this agent remain reversible as long as the `kid` keys are still present. This is intentional — deleting an agent must not break existing audit history.
5. An `agent_deleted` event is appended to the audit log with a timestamp.

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE \
    -H "Cookie: masker_session=ey..." \
    https://masker-voice.fly.dev/api/v1/agents/agt_01HYZ...
  ```
</CodeGroup>

A successful request returns `204 No Content` with an empty body.

## Recovering from accidental deletion

There is no automatic recovery. The audit log records the deletion event with a timestamp and the acting user. If you need to restore the agent's configuration, retrieve the most recent compliance report for that agent — it contains a full configuration snapshot. You can use those settings to recreate the agent manually.

## Errors

| Status | Code              | Meaning                                                      |
| ------ | ----------------- | ------------------------------------------------------------ |
| `401`  | `unauthenticated` | Missing or invalid `masker_session` cookie                   |
| `403`  | `forbidden`       | The signed-in user is not an account admin                   |
| `404`  | `agent_not_found` | No agent with this ID exists, or it has already been deleted |