# Create a new formation

> Validates the template, creates the formation record, then provisions all declared resources in dependency order.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new formation"}
>
</Heading>

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

Validates the template, creates the formation record, then provisions all declared resources in dependency order.

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

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

<ParamsDetails>
  
</ParamsDetails>

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

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