Delete an formation
DELETE/v1/projects/:project_id/formations/:formation_id
Deletes the formation stack and all its managed resources in reverse dependency order.
A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with 409 FORMATION_DELETE_FAILED, naming every blocking resource in error.meta.failures. Resolve the blockers (for an agent, DELETE /v1/projects/{project_id}/agents/{agent_id}?force=true also removes its generations and traces, and deletion_policy: retain exempts it from teardown entirely) and delete the formation again.
A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays active and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in delete_failed. The error message states which happened.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 500
- 502
- 4XX
Deleted
The request was malformed or failed validation.
Unauthorized
Forbidden — either the caller may not operate on formations in the project, or it lacks an action a resource this template declares requires. error.meta.denied_actions names every missing action; nothing is applied.
Not Found
One or more resources could not be deleted (FORMATION_DELETE_FAILED). error.meta.failures lists each one as { logical_id, resource_type, error }. The message says whether the pre-flight caught it (nothing deleted, formation still active) or it surfaced mid-teardown (formation left in delete_failed).
QUOTA_EXCEEDED — a requests quota on the calling API key or its project is spent for the window; Retry-After says when it reopens
Response Headers
Seconds until the quota window admits a request again
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
The deployment's admission service is asked about this write and did not answer — ADMISSION_UNAVAILABLE; the write did not happen
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there