Agent Lifecycle

Deregister (delete) a cloud agent and cascade-clean everything attached to it. Deregistration tears down running deployments (Railway containers + ZeroDB resources), revokes the agent's OAuth clients and access tokens, and removes its schedules — then soft- or hard-deletes the registration.

Base path: /api/v1/cloud/agents

You must be the agent's owner.

DELETE /{agent_id}

Deregister an agent. By default this is a reversible soft-delete (status='DELETED', hidden from all listings). Pass hard_delete=true to physically remove the registration row.

# Soft delete (default, reversible by support)
curl -X DELETE https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6 \
  -H "Authorization: Bearer $TOKEN"

# Hard delete (physically removes the row)
curl -X DELETE "https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6?hard_delete=true" \
  -H "Authorization: Bearer $TOKEN"

Query parameters:

Parameter	Type	Default	Description
`hard_delete`	bool	`false`	`false` = soft-delete (reversible). `true` = physically delete the registration row.

Response (200):

{
  "agent_id": "agent-a1b2c3d4e5f6",
  "deregistered": true,
  "hard_deleted": false,
  "deployments_torn_down": 1,
  "oauth_clients_revoked": 2,
  "schedules_removed": 3
}

The deployments_torn_down, oauth_clients_revoked, and schedules_removed counts report exactly what was cleaned up as part of the cascade.

Errors:

Status	Meaning
`404 Not Found`	No agent with that `agent_id`.
`403 Forbidden`	You are not the owner of this agent.

DELETE /{agent_id}​

DELETE /{agent_id}