# Update an formation

> Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an formation"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/formations/{formation_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.

A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.

A deploy that replaced a resource and could not delete the superseded one answers `status: "active"` with `error.code: "FORMATION_REPLACE_CLEANUP_FAILED"` — the desired state is realised, and `error.meta.failures` names every resource still live. The next deploy retries the disposal.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-formation.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-formation.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-formation.StatusCodes.json")}
>
  
</StatusCodes>