Users & agents

Delete an agent

Hard-delete an agent namespace in the key's project: 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 List agents shows for this key (used in this key's project); any other name, including one used only in another project, returns `404`. Percent-encode it as one path segment (`a/b` is `a%2Fb`); any stored id is accepted.

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",
  "slot_freed": true
}

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	Id of the receipt Korely keeps for this purge (`aud_` and 32 hex characters). The audit log also records an `erase` event, with `target_id` `agent:<agent_id>`.
`slot_freed`	boolean	Whether the agent cap slot is free now. The cap counts a name across the account, so it stays `false` while another project of the account still uses this `agent_id`; this key cannot see or delete that project's rows.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Invalid or missing API key: ...`, then what is wrong.
`403`	`forbidden`	The key lacks the required scope, `API key missing required scope(s): memories:write`.
`404`	`not_found`	The namespace is not used in this key's project, `No agent namespace '<agent_id>' in this key's project.`
`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, and the slot is free when no other project of the account uses the same agent_id (see slot_freed).
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.
Audited. The purge leaves a receipt (audit_id) and an erase event in the audit log, counts only.
Write scope required. The key must carry memories:write.

List agents, enumerate the namespaces of this key's project before deleting one.
Forget a user, the permanent end-user-scoped erasure (it frees an agent slot only if no row carrying that agent_id remains in the account).
SDK reference, the full surface across cURL, Python, and Node.