Users & agents

Delete an agent

Hard-delete an agent namespace in the key's project: purge every memory and fact stored under it. This frees its cap slot in this project.

DELETE /v1/agents/{agent_id}

SDK: korely.delete_agent(agent_id). The Glossary defines the words used across the docs.

This call deletes for good. Try it on a throwaway agent_id first.

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 permission (the API calls it a 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_..."

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

receipt = korely.delete_agent("support-triage")

print(receipt.memories_deleted, receipt.facts_deleted)  # 4 9
print(receipt.audit_id)  # "aud_9f44c1d27b0a4e1c8d5f3a6b2e7c9d10"

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const receipt = await korely.deleteAgent("support-triage");

console.log(receipt.memories_deleted, receipt.facts_deleted); // 4 9
console.log(receipt.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,
  "facts_reopened": 0,
  "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.
`facts_reopened`	integer	Facts of other namespaces that this namespace had closed and that are true again now that it is gone. Each comes back as a new open fact, decided on the stored rows with no model; when it is not clear, a fact stays closed. A namespace is everything written under one `agent_id`, and a fact is reopened when it becomes true again as a new open fact. Example: agents a and b both know "I live in Paris"; agent c then writes "now I live in Zanzibar", which closes both Paris facts. Deleting c's namespace gives Paris back to a and to b, and the count is 2 (since 1.0.8; before, only one copy came back). `0` when none did. Since 1.0.14, a fact that was forgotten, corrected or posted in the past tense by hand is not given back (see Delete a memory). The SDKs (Python 0.1.28, Node.js 0.1.17) do not carry this field in their receipt: read the response body to see it.
`read_marks_deleted`	integer	Count of read marks deleted: the marks whose reader's name is this agent's, in its project (since 1.0.15).
`audit_id`	string	Id of the receipt Korely keeps for this purge (`aud_` and 32 hex characters). It comes once, in this response, and no call reads it back. The audit log also records an `erase` event, with the `agent_id` itself as `target_id`.

The server sends no slot_freed field. The SDKs' receipts have a field of that name, and it stays empty: to see whether the slot is free, read cap and used in List agents.

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`	The account hit its rate limit. Honor the `Retry-After` header and retry.
`503`	`unavailable`	The database is busy with another change to the same data, or did not answer. Nothing was deleted; retry after the seconds in `Retry-After`.

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 this project: deleting the namespace is the direct way. The cap counts an agent once per project and name (queued batches included), so another project that uses the same name keeps its own slot; GET /v1/agents (cap, used) shows the account's total.
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.
Also removed. The names declared in that namespace (Declare a name with its agent_id) and the items of POST /v1/batch imports that name the agent, which are scrubbed from the import, queued or finished, so a queued import does not write the agent back.
The end user's data under other agents stays. Only this namespace is purged. To erase one end user across every agent, use Erase a user.
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. A confined key cannot delete a namespace, because a namespace spans every end user.

List agents, enumerate the namespaces of this key's project before deleting one.
Erase 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.

Delete an agent

Authentication

Path parameter

Example request

Response

Errors

Notes

Related