curl -X DELETE "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
agent_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
response = requests.delete(agent_url, headers=headers)
if response.status_code == 204:
print("Agent deleted")
elif response.status_code == 409:
# Not terminal yet — cancel, then delete.
requests.post(f"{agent_url}/cancel", headers=headers)
requests.delete(agent_url, headers=headers)
else:
print(f"Error: {response.json()['errors']}")
const agentUrl = `${process.env.ATAI_API_URL}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f`;
const headers = { 'Authorization': `Bearer ${process.env.ATAI_API_KEY}` };
const response = await fetch(agentUrl, { method: 'DELETE', headers });
if (response.status === 204) {
console.log('Agent deleted');
} else if (response.status === 409) {
// Not terminal yet — cancel, then delete.
await fetch(`${agentUrl}/cancel`, { method: 'POST', headers });
await fetch(agentUrl, { method: 'DELETE', headers });
} else {
const body = await response.json();
console.error('Error:', body.errors);
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent is not in a terminal state (cancel it first).",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Agents API
Delete Agent
Delete a terminal agent run
DELETE
/
agents
/
instances
/
{agent_id}
curl -X DELETE "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
agent_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
response = requests.delete(agent_url, headers=headers)
if response.status_code == 204:
print("Agent deleted")
elif response.status_code == 409:
# Not terminal yet — cancel, then delete.
requests.post(f"{agent_url}/cancel", headers=headers)
requests.delete(agent_url, headers=headers)
else:
print(f"Error: {response.json()['errors']}")
const agentUrl = `${process.env.ATAI_API_URL}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f`;
const headers = { 'Authorization': `Bearer ${process.env.ATAI_API_KEY}` };
const response = await fetch(agentUrl, { method: 'DELETE', headers });
if (response.status === 204) {
console.log('Agent deleted');
} else if (response.status === 409) {
// Not terminal yet — cancel, then delete.
await fetch(`${agentUrl}/cancel`, { method: 'POST', headers });
await fetch(agentUrl, { method: 'DELETE', headers });
} else {
const body = await response.json();
console.error('Error:', body.errors);
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent is not in a terminal state (cancel it first).",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 1.1.9 or later of the Archetype platform.
Overview
This endpoint deletes an agent (bundle run) by itsagt_ id.
Only terminal runs can be deleted. A run that is still running or paused returns 409 — cancel it first with POST /agents/instances/{agent_id}/cancel.
Request
string
required
Agent
agt_ id.Response
Returns204 No Content with an empty body on success.
curl -X DELETE "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_URL"]
api_key = os.environ["ATAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}
agent_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f"
response = requests.delete(agent_url, headers=headers)
if response.status_code == 204:
print("Agent deleted")
elif response.status_code == 409:
# Not terminal yet — cancel, then delete.
requests.post(f"{agent_url}/cancel", headers=headers)
requests.delete(agent_url, headers=headers)
else:
print(f"Error: {response.json()['errors']}")
const agentUrl = `${process.env.ATAI_API_URL}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f`;
const headers = { 'Authorization': `Bearer ${process.env.ATAI_API_KEY}` };
const response = await fetch(agentUrl, { method: 'DELETE', headers });
if (response.status === 204) {
console.log('Agent deleted');
} else if (response.status === 409) {
// Not terminal yet — cancel, then delete.
await fetch(`${agentUrl}/cancel`, { method: 'POST', headers });
await fetch(agentUrl, { method: 'DELETE', headers });
} else {
const body = await response.json();
console.error('Error:', body.errors);
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent not found.",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
{
"errors": [
{
"code": "<error_code>",
"message": "Agent is not in a terminal state (cancel it first).",
"suggestion": null,
"error_uid": "err-xxxxxxxx"
}
]
}
Important Notes
- Terminal statuses are
completed,failed, andcanceled. Arunningorpausedagent must be canceled before it can be deleted. - Success returns
204with no body — check the status code rather than parsing a response.
Was this page helpful?
⌘I