Skip to main content
Stages are the columns of the board. Each stage belongs to a pipeline and has a position that defines its order. Every route on this page requires the pipeline.manage permission.
To create or reorder several stages at once, prefer Configure a pipeline — it is a transactional operation that saves the complete list.

The Stage object

id
string
Stage UUID
name
string
Name displayed at the top of the column
color
string
Color in the token format "H S% L%" (HSL triple without the hsl() wrapper)
kind
string
won, lost, or absent for a regular stage
position
integer
Column order on the board (0-based)

Create a stage

POST /backend/pipelines/{id}/stages
Adds a regular stage to the end of the pipeline. You cannot create won or lost stages — they already exist from the moment the pipeline is created.

Request Body

name
string
required
Stage name
color
string
Color in the "H S% L%" format. When omitted, the default gray "215 16% 47%" is used.

Update a stage

PUT /backend/pipeline/stages/{id}
Renames, recolors or repositions a stage. Omitted fields stay unchanged.

Request Body

name
string
New name
color
string
New color in the "H S% L%" format
position
integer
New position on the board
The won and lost stages can be renamed and recolored normally — it is the kind that does not change. This is how you replace the Portuguese default names (Ganho, Perdido) with English ones.

Delete a stage

DELETE /backend/pipeline/stages/{id}

Query Parameters

target_stage_id
string
Stage that will receive the deals from the deleted stage. Required when the stage still contains deals.
Deleting a stage that still has deals without target_stage_id returns 409. Deals are never removed along with the stage — the API forces you to pick a destination.
The destination must belong to the same pipeline and cannot be the stage being deleted — both cases return 400.
The Won (kind: "won") and Lost (kind: "lost") stages cannot be deleted (400), because there is no route that recreates them. The pipeline must also keep at least one stage.
Error message strings are returned by the API in Portuguese. Match on code (ERR_CONFLICT, ERR_INVALID_INPUT), never on the message text.
Recommended interface flow: try the DELETE without target_stage_id; if you get 409, ask the user where the deals should go and retry with the parameter.