Delete an formation

DELETE 
/api/v1/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 /api/v1/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

Deleted

401

Unauthorized

403

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.

404

Not Found

409

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).