Archive and unarchive a Cloud Agent via API
Soft-delete a Cloud Agent with POST https://api.cursor.com/v1/agents/{id}/archive, then restore it with POST https://api.cursor.com/v1/agents/{id}/unarchive. Official reference: Cloud Agents API → Agent Lifecycle.
The Cloud Agents API v1 is in public beta. Authenticate with Basic auth (API key as username, empty password) or Authorization: Bearer YOUR_API_KEY. Create a user key at Cursor Dashboard → API Keys, or use a service account key. Availability: Beta (all plans) per the API overview.
Archived agents stay readable but cannot accept new runs until you unarchive them. Use archive for reversible cleanup; use permanent delete only when you mean to erase the agent.
Archive
Path parameter id is the agent id (bc-…). Archive is idempotent: re-archiving an already-archived agent returns 200 with no change.
curl --request POST \
--url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \
-u YOUR_API_KEY:
Response:
{
"id": "bc-00000000-0000-0000-0000-000000000001"
}
After archive, Get An Agent reports status: "ARCHIVED". That status is terminal for claims and workspace retention until you unarchive.
Unarchive
curl --request POST \
--url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \
-u YOUR_API_KEY:
Response:
{
"id": "bc-00000000-0000-0000-0000-000000000001"
}
Unarchive is also idempotent: calling it on an already-active agent returns 200 with no change. After a successful unarchive, Create A Run works again on the same agent id.
List filter
GET /v1/agents accepts includeArchived (default true). Set includeArchived=false when you want only non-archived agents in the list.