Resources
Pipelines & Stages
A pipeline is a board with ordered stages. Opportunities and projects move through a pipeline's stages over their lifecycle. Read these endpoints to discover the stage ids you need when creating an opportunity, and write to them to keep a workspace's board in step with whatever system you are syncing from.
Permissions
Reads need nothing beyond a valid key. Every write requires the workspace member who generated the key to hold pipelines.manage, the same permission the board itself checks, so a key cannot reshape a pipeline its owner could not reshape by hand. Every write is recorded in the workspace's audit log against that member.
Creating a pipeline counts against the workspace plan the same way creating one in the app does. A pipeline in another workspace answers 404, never 403.
The closing stage is system-managed
A project pipeline ends in a stage flagged is_terminal, normally named Closed. Moving a project into it archives the project, so it cannot be renamed, moved off the end, or deleted, and a new stage always lands in front of it whatever position you ask for. Check is_terminal before you plan a write.
The stage object
| Field | Type | Description |
|---|---|---|
| id | uuid | Unique id of the stage. This is the stage_id you pass when creating an opportunity. |
| pipeline_id | uuid | The pipeline the stage belongs to. |
| name | string | Stage name as it reads on the board. |
| color | string | Hex color, or null. |
| position | integer | Zero-based order on the board. Always contiguous. |
| is_terminal | boolean | True for the system-managed closing stage. Dropping a project there archives it, so it cannot be renamed, moved, or deleted. |
/v1/pipelinesList pipelines
Returns all pipelines for your workspace. The default pipeline is returned first.
| Query parameter | Type | Description |
|---|---|---|
| type | enum | Filter by pipeline type. One of: opportunity, project, custom. |
/v1/pipelinesCreate a pipeline
Creates a workspace-wide pipeline with its stages, in the order given. A board with no stages has nowhere to put a record, so stages is required.
| Body | Type | Description |
|---|---|---|
| name | string | Required. 120 characters or fewer. |
| type | enum | Required. opportunity or project. |
| stages | string[] | Required. Between 1 and 50 stage names, in board order. |
/v1/pipelines/{id}Rename a pipeline
Takes nameand nothing else. Pipelines cannot be deleted through the API: removing a board takes every record's placement on it, so that stays an action somebody takes in the app with the confirmation in front of them.
/v1/stagesList stages for a pipeline
Returns the ordered stages for a single pipeline.
| Query parameter | Type | Description |
|---|---|---|
| pipeline_id | uuid | Required. The pipeline whose stages you want. |
/v1/stagesAdd a stage
Appends a stage to a pipeline, or inserts it at position. Positions past the end clamp rather than erroring, and every other stage is renumbered so positions stay contiguous.
| Body | Type | Description |
|---|---|---|
| pipeline_id | uuid | Required. The pipeline to add to. |
| name | string | Required. 120 characters or fewer. |
| position | integer | Zero-based. Appends when omitted. Never places the stage behind the closing stage. |
| color | string | Hex color such as #0073E6, or null. |
/v1/stages/{id}Rename, recolor, or move a stage
Every field is optional; only what you send changes. Sending positionreorders the pipeline around the stage. The closing stage accepts a color and refuses a rename or a move.
| Body | Type | Description |
|---|---|---|
| name | string | 120 characters or fewer. |
| position | integer | Zero-based target position. |
| color | string | Hex color, or null to clear it. |
/v1/stages/{id}Delete a stage
Records sitting on a stage have to go somewhere, so destination_stage_id is required and must name another stage on the same pipeline. Every record moves there, then the stage is removed and the pipeline renumbered. The response reports how many moved.
A pipeline always keeps at least one working stage, so the last one refuses to delete, and so does the closing stage.
| Query parameter | Type | Description |
|---|---|---|
| destination_stage_id | uuid | Required. Where the records on this stage move to. |