Delete an agent

Soft-delete an agent. Restorable from the dashboard trash for 30 days.

DELETE /api/v1/agents/:id

Soft delete. The agent moves to the dashboard trash and is restorable for 30 days. After 30 days the cleanup scheduler hard-deletes.

Scope: agents:delete

Path parameters

Param	Type	Notes
`:id`	string	Agent ID (prefixed or bare).

Side effects

All triggers on the agent are deactivated. External webhooks (Zendesk) are torn down so traffic stops immediately.
Chatbots bound to the agent are paused.
The agent disappears from GET /agents listings but is visible in the dashboard's trash view.

Example request

curl -X DELETE https://dashboard.getmacha.com/api/v1/agents/agent_64f1c0... \
  -H "Authorization: Bearer $MACHA_API_KEY"

Example response (200)

{
  "data": { "id": "agent_64f1c0...", "deleted": true },
  "meta": { "request_id": "req_..." }
}

Idempotency

DELETE is naturally idempotent, the second call returns 404 agent_not_found instead of a duplicate effect. No need to pass Idempotency-Key.

Restoring a deleted agent

There's no API endpoint to restore yet, head to the dashboard's trash view to restore. When that's added it'll appear here.

Errors

Status	Code	When
`401`	`unauthorized`	Bad / missing key.
`403`	`insufficient_scope`	Key lacks `agents:delete`.
`404`	`agent_not_found`	Unknown ID or already deleted past trash window.
`429`	`rate_limited`	Per-key ceiling exceeded.

⛔

Triggers are torn down, not deactivated

Deleting an agent calls the connector's webhook-delete API. Restoring the agent later won't auto-restore the external webhooks, you'll have to recreate triggers manually or wait for the cascade restore (planned but not yet shipped).