Permanently delete agent
Permanently delete this agent, IRREVERSIBLE. Removes the agent and cascades to every version, tool, variable, eval, and the call-transcript links. There is no recovery. Only an archived agent can be deleted: call `archive_agent` first, which stops its calls and unassigns its numbers (they stay in the workspace), the same two steps as the Archive or delete page. Prefer archiving alone (reversible) unless the agent must be erased for good. Over MCP this requires `confirm: true`.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/operations/permanent_delete_agent" \ -H "Content-Type: application/json" \ -d '{ "agent": "string" }'{}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Override run verdict POST
Set a manual verdict on an eval run (success / failure / review_required) without overwriting the engine's computed result, it writes a separate override row, one per run. Use this when the automated pass/fail is wrong or a run needs a human to look. The run must belong to the current agent.
Read a building guide POST
Return one of the guides for building a good agent, in full, as markdown. Read the right one before you write config: 'build-an-agent' before a new build, 'system-prompt' and 'voice-craft' before update_system_prompt, edit_system_prompt or set_tool_description, and 'test-an-agent' before you write or run tests. The guides: 'build-an-agent' (building a new agent), 'system-prompt' (writing prompts and tool descriptions), 'voice-craft' (voice craft), 'test-an-agent' (testing an agent until it's ready). The same text is served as the vai://guides resources and as pages on the public docs.