Users & agents

Delete an agent

Hard-delete an agent namespace in the key's project: purge every memory and fact stored under it, which frees its cap slot unless another project of the account still holds the name.

DELETE /v1/agents/{agent_id}

This is a hard delete (a purge), not the soft forget used elsewhere. Forgetting memories never frees a slot: the cap counts every row that carries the agent_id, forgotten and closed rows included. A slot frees when no row carrying the name is left in the account: deleting the namespace is the direct way.

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_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"

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_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"

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": 4,
  "facts_deleted": 9,
  "audit_id": "aud_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"
}

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 the `agent_id` itself as `target_id`.

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 `memories:write` (`API key missing required scope(s): memories:write`), or it is confined to some end users (an agent namespace spans every end user).
`404`	`not_found`	The namespace is not used in this key's project, `No agent namespace '<agent_id>' in this project.`
`422`	`invalid_request`	`agent_id` is longer than 255 characters or holds a NUL byte.
`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.
Frees the cap slot. The cap set counts any row carrying the agent_id, including soft-deleted and invalidated rows. A slot frees when no row carrying the name is left in the account: deleting the namespace is the direct way. The cap counts a name across the account (queued batches included), so the slot is free only when no other project of the account still uses this agent_id; GET /v1/agents (cap, used) shows it.
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.