> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/pipelines.md).

# Pipelines

Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through.

## GET /pipelines

> List sales pipelines.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines":{"get":{"tags":["Pipelines"],"operationId":"listPipelines","summary":"List sales pipelines.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}}}}]}}}}}}}}}
```

## Create a pipeline.

> Requires the pipeline name. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"PipelineCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"is_default":{"type":"boolean","default":false},"owner_id":{"$ref":"#/components/schemas/StaffId"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines":{"post":{"tags":["Pipelines"],"operationId":"createPipeline","description":"Requires the pipeline name. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","summary":"Create a pipeline.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pipeline"}}}}}}}}}
```

## Retrieve one sales pipeline.

> The pipeline's name, its stages in order, and whether it is the account default. Sales-automation rules reference a pipeline by this ID.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}":{"get":{"tags":["Pipelines"],"operationId":"retrievePipeline","summary":"Retrieve one sales pipeline.","description":"The pipeline's name, its stages in order, and whether it is the account default. Sales-automation rules reference a pipeline by this ID.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pipeline"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a pipeline's name or default flag.

> Patches the pipeline itself, not its stages — use the stage operations for those. Omitted fields are left unchanged.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineUpdate":{"type":"object","description":"Fields to patch on a sales pipeline. All fields are optional. Omitted fields are left unchanged.\n","properties":{"name":{"type":"string","description":"Display name of the pipeline."},"is_default":{"type":"boolean","description":"Whether this pipeline is the default sales pipeline for the workroom. Setting true makes this the default and clears the default flag on any previous default pipeline. Omit to leave unchanged (no default false).\n"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true,"description":"Staff user who owns this pipeline."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}":{"patch":{"tags":["Pipelines"],"operationId":"updatePipeline","summary":"Update a pipeline's name or default flag.","description":"Patches the pipeline itself, not its stages — use the stage operations for those. Omitted fields are left unchanged.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pipeline"}}}}}}}}}
```

## DELETE /pipelines/{id}

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}}},"paths":{"/pipelines/{id}":{"delete":{"tags":["Pipelines"],"operationId":"deletePipeline","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Deleted. Cascades to stages."}}}}}}
```

## List a pipeline's stages, in order.

> Stages in their display order, with the contact count in each. Stage order is what the dashboard's kanban columns follow; change it with \`reorderPipelineStages\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}/stages":{"get":{"tags":["Pipelines"],"operationId":"listPipelineStages","summary":"List a pipeline's stages, in order.","description":"Stages in their display order, with the contact count in each. Stage order is what the dashboard's kanban columns follow; change it with `reorderPipelineStages`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Stages sorted by `order` ASC.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"}}}}]}}}}}}}}}
```

## POST /pipelines/{id}/stages

> Requires the stage name and its position. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineStageCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"order":{"type":"integer","description":"Optional. Defaults to end of list."},"color":{"type":"string"},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"default":"manual","description":"`manual` (default) → no criteria. `static` / `dynamic` → `criteria` is required. See the PipelineStage schema for semantics.\n"},"criteria":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required when `stage_type` is `static` or `dynamic`. Segment_users DSL — AND-joined. See `GET /segments/schema`. Normalized and validated exactly as segment conditions are: an operator the field's data_type does not support is rejected with 422 `invalid_operator` (on create and on PATCH)."},"with_or_criteria":{"type":"array","description":"Alternate inclusion groups, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `criteria` and every other group. Use this to build \"criteria A OR criteria B\" stage membership without touching `criteria`. Optional; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"owner_id":{"$ref":"#/components/schemas/StaffId"}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}/stages":{"post":{"tags":["Pipelines"],"operationId":"createPipelineStage","description":"Requires the stage name and its position. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStageCreate"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStage"}}}}}}}}}
```

## Retrieve one pipeline stage.

> The stage's name, position and the pipeline it belongs to. Note that sales-automation rules match a trigger stage by NAME within their own pipeline, not by this ID.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}/stages/{stage_id}":{"get":{"tags":["Pipelines"],"operationId":"retrievePipelineStage","summary":"Retrieve one pipeline stage.","description":"The stage's name, position and the pipeline it belongs to. Note that sales-automation rules match a trigger stage by NAME within their own pipeline, not by this ID.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStage"}}}}}}}}}
```

## Rename or move a pipeline stage.

> Renaming a stage rewrites the \`trigger\_stage\` of any sales-automation rule that referenced the old name, since rules match stages by name.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineStageUpdate":{"type":"object","description":"Fields to patch on a pipeline stage. All fields are optional. Omitted fields are left unchanged.\n","properties":{"name":{"type":"string","description":"Display name of the stage."},"order":{"type":"integer","description":"1-based position among stages in this pipeline."},"color":{"type":"string","description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"`manual` → no criteria. `static` / `dynamic` → criteria required. Omit to leave unchanged.\n"},"criteria":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required when changing stage_type to static or dynamic."},"with_or_criteria":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}/stages/{stage_id}":{"patch":{"tags":["Pipelines"],"operationId":"updatePipelineStage","summary":"Rename or move a pipeline stage.","description":"Renaming a stage rewrites the `trigger_stage` of any sales-automation rule that referenced the old name, since rules match stages by name.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStageUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStage"}}}}}}}}}
```

## DELETE /pipelines/{id}/stages/{stage\_id}

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}}},"paths":{"/pipelines/{id}/stages/{stage_id}":{"delete":{"tags":["Pipelines"],"operationId":"deletePipelineStage","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Deleted."}}}}}}
```

## Reorder stages within a pipeline.

> Body \`{stage\_ids: \["stg\_..."]}\` in desired display order. Assigns \`order = 1..N\`.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/{id}/stages/reorder":{"post":{"tags":["Pipelines"],"operationId":"reorderPipelineStages","summary":"Reorder stages within a pipeline.","description":"Body `{stage_ids: [\"stg_...\"]}` in desired display order. Assigns `order = 1..N`.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stage_ids"],"properties":{"stage_ids":{"type":"array","items":{"$ref":"#/components/schemas/StageId"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"}}}}]}}}}}}}}}
```

## Duplicate a pipeline.

> Creates a new pipeline with the same stages (name, type, criteria, order, color, owner). Each static/dynamic stage gets a fresh shadow segment recomputed from its criteria — no contact membership is copied; the new pipeline's stages start empty until the background worker recomputes them, exactly as a newly created stage would. \`is\_default\` is NOT copied — the duplicate is never made the account's default pipeline.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}/duplicate":{"post":{"tags":["Pipelines"],"operationId":"duplicatePipeline","summary":"Duplicate a pipeline.","description":"Creates a new pipeline with the same stages (name, type, criteria, order, color, owner). Each static/dynamic stage gets a fresh shadow segment recomputed from its criteria — no contact membership is copied; the new pipeline's stages start empty until the background worker recomputes them, exactly as a newly created stage would. `is_default` is NOT copied — the duplicate is never made the account's default pipeline.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the duplicate. Defaults to `\"<source name> (copy)\"`."}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pipeline"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Reorder the top-level pipelines list.

> Reorders pipelines themselves — distinct from \`POST /v3/pipelines/{id}/stages/reorder\`, which only reorders stages within one pipeline. Body \`{pipeline\_ids: \["pip\_..."]}\` in desired display order; assigns \`sort\_order = 1..N\`. Pipelines that have never been reordered (no \`sort\_order\` set) sort AFTER every explicitly-ordered pipeline in \`GET /v3/pipelines\`, not interleaved by creation date. Malformed or unresolvable ids are skipped silently. The response returns only the pipelines passed in this call, shaped and in the order provided — not the full \`listPipelines\` page.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"schemas":{"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Pipeline":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/PipelineId"},"object":{"type":"string","enum":["pipeline"]},"name":{"type":"string"},"is_default":{"type":"boolean"},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"active_linked_children":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"},"description":"Stages belonging to this pipeline, in display order."},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineStage":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/StageId"},"object":{"type":"string","enum":["pipeline_stage"]},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"name":{"type":"string"},"order":{"type":"integer","description":"1-based; lower renders first (leftmost in the pipeline board)."},"color":{"type":"string","nullable":true,"description":"Background color hex."},"stage_type":{"type":"string","enum":["manual","static","dynamic"],"description":"How contacts arrive in this stage:\n  - `manual` (default) — contacts are added by hand or by an automation. No criteria.\n  - `static` — one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).\n  - `dynamic` — continuous criteria; the background worker keeps the stage's membership in sync with the criteria — new matches roll in, non-matches roll out.\n"},"criteria":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Required for `static` and `dynamic` stages. Same `segment_users` DSL as segments — AND-joined. Call `GET /segments/schema` for the vocabulary. Stored exactly as a segment's conditions are (engine `segment` tokens, engine-native operators, Date `<`/`>` as `Before`/`After`), so this echoes the stored form, not necessarily the aliases you sent."},"with_or_criteria":{"type":"array","nullable":true,"description":"Alternate inclusion groups, same semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with `criteria` and every other group. A contact matching `criteria` OR any one group is included. Only meaningful when `stage_type` is `static` or `dynamic`; ignored on `manual` stages.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"segment_id":{"$ref":"#/components/schemas/SegmentId","nullable":true,"description":"Auto-created shadow segment when `stage_type` is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API."},"owner_id":{"$ref":"#/components/schemas/StaffId","nullable":true},"contact_count":{"type":"integer","description":"Number of contacts currently in this stage."},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/pipelines/reorder":{"post":{"tags":["Pipelines"],"operationId":"reorderPipelines","summary":"Reorder the top-level pipelines list.","description":"Reorders pipelines themselves — distinct from `POST /v3/pipelines/{id}/stages/reorder`, which only reorders stages within one pipeline. Body `{pipeline_ids: [\"pip_...\"]}` in desired display order; assigns `sort_order = 1..N`. Pipelines that have never been reordered (no `sort_order` set) sort AFTER every explicitly-ordered pipeline in `GET /v3/pipelines`, not interleaved by creation date. Malformed or unresolvable ids are skipped silently. The response returns only the pipelines passed in this call, shaped and in the order provided — not the full `listPipelines` page.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pipeline_ids"],"properties":{"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pipeline"}}}}]}}}}}}}}}
```

## GET /pipelines/{id}/sharing

> Read a pipeline's sharing configuration.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineSharing":{"type":"object","properties":{"object":{"type":"string","const":"pipeline_sharing"},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}/sharing":{"get":{"tags":["Pipelines"],"operationId":"retrievePipelineSharing","summary":"Read a pipeline's sharing configuration.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineSharing"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Replace a pipeline's sharing configuration.

> Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: \`me\`, \`Admin\`, \`WorkroomAdmin\`, \`Marketing\`, \`Sales\`, \`Analyst\`, \`Other\`. When \`Other\` is true, \`other\_allowed\_user\_ids\[]\` must contain at least one valid staff ID or 400 is returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineSharingUpdate":{"type":"object","properties":{"allowed_roles":{"type":"object","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Required (non-empty) when `allowed_roles.Other` is true; otherwise ignored."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"PipelineSharing":{"type":"object","properties":{"object":{"type":"string","const":"pipeline_sharing"},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}/sharing":{"put":{"tags":["Pipelines"],"operationId":"updatePipelineSharing","summary":"Replace a pipeline's sharing configuration.","description":"Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. When `Other` is true, `other_allowed_user_ids[]` must contain at least one valid staff ID or 400 is returned.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineSharingUpdate"}}}},"responses":{"200":{"description":"Updated sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineSharing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Add or move a contact to a stage within a pipeline — direct and synchronous.

> Sets the contact's current stage in this pipeline right now, regardless of prior state: if the contact isn't in the pipeline yet, this adds them; if they're already in it, this moves them. There is no separate "add" endpoint — the two are the same write, distinguished only by \`previous\_stage\_id\` in the response (\`null\` = fresh add or idempotent no-op).\
> \
> Works on a stage of ANY \`stage\_type\` — including \`static\`/\`dynamic\` stages whose membership is normally computed from criteria by a background worker. This plants a manual-override marker (mirroring the dashboard's own drag-and-drop behavior) that protects the contact against backward or equal-stage moves during background criteria sync. Note that in standard Gleantap pipeline semantics, downstream dynamic stages with a higher display order can advance a matching contact forward when criteria match. Re-\`GET\` the contact or pipeline contact membership to observe current placement.\
> \
> Idempotent: calling this again with the same \`stage\_id\` the contact is already at is a safe no-op — no duplicate history entries are written.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"PipelineMembershipSet":{"type":"object","required":["stage_id"],"properties":{"stage_id":{"$ref":"#/components/schemas/StageId"}}},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"PipelineMembership":{"type":"object","description":"A contact's current position within one pipeline. There is no \"in the pipeline but no stage\" state — a contact either has exactly one of these, or isn't in the pipeline at all.\n","properties":{"object":{"type":"string","const":"pipeline_membership"},"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true,"description":"Display name of the current stage."},"status":{"type":"string","enum":["Active","Won","Lost","Archived"],"description":"Independent of stage — changed separately (e.g. by a sales_automation `status` action), not by moving stages."},"priority":{"type":"string","nullable":true},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"},"previous_stage_id":{"$ref":"#/components/schemas/StageId","nullable":true,"description":"Only present on the PUT response. `null` if the contact was not previously in this pipeline (a fresh add) or was already at that stage (idempotent no-op — nothing was written). Otherwise the stage they were moved FROM."}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}/contacts/{contact_id}":{"put":{"tags":["Pipelines"],"operationId":"setPipelineContactStage","summary":"Add or move a contact to a stage within a pipeline — direct and synchronous.","description":"Sets the contact's current stage in this pipeline right now, regardless of prior state: if the contact isn't in the pipeline yet, this adds them; if they're already in it, this moves them. There is no separate \"add\" endpoint — the two are the same write, distinguished only by `previous_stage_id` in the response (`null` = fresh add or idempotent no-op).\n\nWorks on a stage of ANY `stage_type` — including `static`/`dynamic` stages whose membership is normally computed from criteria by a background worker. This plants a manual-override marker (mirroring the dashboard's own drag-and-drop behavior) that protects the contact against backward or equal-stage moves during background criteria sync. Note that in standard Gleantap pipeline semantics, downstream dynamic stages with a higher display order can advance a matching contact forward when criteria match. Re-`GET` the contact or pipeline contact membership to observe current placement.\n\nIdempotent: calling this again with the same `stage_id` the contact is already at is a safe no-op — no duplicate history entries are written.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineMembershipSet"}}}},"responses":{"200":{"description":"The contact's current membership record, including where they were before this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineMembership"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Remove a contact from a pipeline entirely — direct and synchronous.

> Removes the contact's ENTIRE membership in this pipeline — there is no "stay in the pipeline but clear the stage" state to target, so this always removes them from every stage of it, not just one.\
> \
> Requires \`expected\_stage\_id\` (query parameter) naming the stage you believe the contact is currently at, as an optimistic-concurrency check — if it doesn't match their actual current stage, this returns 409 and writes nothing. Re-\`GET\` the contact or pipeline first if you're not sure.\
> \
> This is treated as a MANUAL removal, same as the dashboard's own delete action — which means it is NOT a cheap, reversible action: it plants a permanent marker that blocks this contact from ever being silently re-added to this pipeline by an automation or by stage criteria again, even though the contact document itself is otherwise untouched. Calling the add/move endpoint again for this contact and pipeline overrides that block for that one explicit call, but nothing else will re-add them on its own afterward. Only use this when removal is really intended.\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Pipelines","description":"Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/pipelines/{id}/contacts/{contact_id}":{"delete":{"tags":["Pipelines"],"operationId":"removePipelineContact","summary":"Remove a contact from a pipeline entirely — direct and synchronous.","description":"Removes the contact's ENTIRE membership in this pipeline — there is no \"stay in the pipeline but clear the stage\" state to target, so this always removes them from every stage of it, not just one.\n\nRequires `expected_stage_id` (query parameter) naming the stage you believe the contact is currently at, as an optimistic-concurrency check — if it doesn't match their actual current stage, this returns 409 and writes nothing. Re-`GET` the contact or pipeline first if you're not sure.\n\nThis is treated as a MANUAL removal, same as the dashboard's own delete action — which means it is NOT a cheap, reversible action: it plants a permanent marker that blocks this contact from ever being silently re-added to this pipeline by an automation or by stage criteria again, even though the contact document itself is otherwise untouched. Calling the add/move endpoint again for this contact and pipeline overrides that block for that one explicit call, but nothing else will re-add them on its own afterward. Only use this when removal is really intended.\n\n**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"expected_stage_id","in":"query","required":true,"schema":{"$ref":"#/components/schemas/StageId"},"description":"The stage you expect the contact to currently be at in this pipeline. Required — this is the optimistic-concurrency check that must pass before anything is removed."}],"responses":{"204":{"description":"Removed."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}}}}
```
