---
title: "Delete agent"
method: DELETE
path: "/agents/{agentKey}"
tags: ["Agents"]
---

# Delete agent

`DELETE /agents/{agentKey}`

Soft-delete an agent (tombstone) in the graph database.

**Overview:**
The Python query service marks the agent instance deleted inside a transaction.
List and search endpoints exclude tombstoned agents. Toolsets, tools, and
knowledge linked to the agent are not removed by this call.

**Permissions:**
Only the agent owner may delete (`can_delete` on the permission check).

**Warning:**
All conversations with this agent will become inaccessible.

**Gateway not-found behavior:**
Unknown `agentKey`, deleting an already-deleted agent, and `GET /agents/{agentKey}`
after delete return **HTTP 404** with an `ErrorResponse` body.

## Path parameters

- `agentKey` string, required

## Response `200`

Agent soft-deleted successfully

- AgentDeleteResponse
  - `status` 'success', required
  - `message` string, required
  - `deleted` object, required
    - `agents` integer, required
    - `toolsets` integer, required
    - `tools` integer, required
    - `knowledge` integer, required
    - `edges` integer, required

## Other responses

- `401` — Missing or invalid bearer token (e.g. `No token provided`)
- `404` — Agent not found, inaccessible, or already deleted.
- `500` — Unexpected AI-backend or gateway failure.

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)