curl -X DELETE "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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"
}
]
}
Instances
Delete Agent
Delete a terminal agent run
DELETE
/
agents
/
instances
/
{agent_id}
curl -X DELETE "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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.
Starting with version 2.0.1, this endpoint is removed from the platform. Use Delete Session instead. To move existing code, see Migrating from Bundles and Instances.
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 an HTTP
409 status code; cancel it first with Cancel
Agent.
Request
Response
Returns204 No Content with an empty body on success.
curl -X DELETE "$ATAI_API_ENDPOINT/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f" \
-H "Authorization: Bearer $ATAI_API_KEY"
import os
import requests
base_url = os.environ["ATAI_API_ENDPOINT"]
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_ENDPOINT}/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, andcancelled. Arunningorpausedagent must be cancelled before it can be deleted. - Success returns
204with no body — check the status code rather than parsing a response.
Was this page helpful?