Users & agents

Delete an agent

Hard-delete an agent namespace: purge every memory and fact stored under it and free its cap slot. This is the only call that reclaims a slot.

DELETE /v1/agents/{agent_id}

This is a hard delete (a purge), not the soft forget used elsewhere. It is the only way to free a cap slot: the agent cap counts every row that carries the agent_id, including soft-deleted and invalidated rows, so soft-forgetting memories does not reclaim a slot. Deleting the namespace does.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key must carry the memories:write scope.

Path parameter

Parameter	Type	Required	Description
`agent_id`	string	Required	The agent namespace to purge. Must be a namespace already in use on this account, see List agents. Unknown namespaces return `404`.

This endpoint takes no query parameters and no request body.

Example request

curl -X DELETE https://api.korely.ai/v1/agents/support-triage \
  -H "Authorization: Bearer kor_live_..."

import requests

resp = requests.delete(
    "https://api.korely.ai/v1/agents/support-triage",
    headers={"Authorization": "Bearer kor_live_..."},
)
resp.raise_for_status()

print(resp.json()["audit_id"])  # "aud_9f44c1"

const resp = await fetch(
  "https://api.korely.ai/v1/agents/support-triage",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer kor_live_..." },
  },
);

const result = await resp.json();
console.log(result.audit_id); // "aud_9f44c1"

Response

200 OK. The purged namespace plus the counts of rows hard-deleted and the id of the audit record.

{
  "agent_id": "support-triage",
  "memories_deleted": 0,
  "facts_deleted": 0,
  "audit_id": "aud_9f44c1"
}

Field	Type	Description
`agent_id`	string	The agent namespace that was purged (echoes the path parameter).
`memories_deleted`	integer	Count of memory rows hard-deleted.
`facts_deleted`	integer	Count of fact rows hard-deleted. Facts are deleted first, including those written straight to `/v1/facts` with no source memory.
`audit_id`	string	Public id of the audit record for this purge (scope `agent`), e.g. `aud_9f44c1`.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Invalid or missing API key`.
`403`	`forbidden`	The key lacks the required scope, `API key missing required scope(s): memories:write`.
`404`	`not_found`	The namespace was never used on this account, `No agent namespace '...' on this account.`
`429`	`rate_limit_exceeded`	Rate limit exceeded. Honor the `Retry-After` header and retry.

Notes

Hard delete, not forget. This is a purge, distinct from the soft forget endpoints. Soft-forgotten rows still count against the agent cap, so forgetting never frees a slot, only deleting the namespace does.
Frees the cap slot. The cap set counts any row carrying the agent_id, including soft-deleted and invalidated rows. Deleting the agent is the one way to reclaim a slot.
Facts go first. Facts are deleted by agent_id directly, so facts written straight to /v1/facts with no source memory are purged too. A fact's source_memory_id is ON DELETE CASCADE.
One audit row. A single audit record is written for the purge (scope agent, target the agent_id).
Write scope required. The key must carry memories:write.

List agents, enumerate the namespaces in use on this account before deleting one.
Forget a user, the soft, end-user-scoped erasure (does not free an agent slot).
SDK reference, the full surface across cURL, Python, and Node.