> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines API

> Manage pipeline structure and read pipeline analytics through the Goliath developer API

## About

Manage your deal pipelines programmatically — list pipelines and their
stages, create new pipelines, edit stage structure — and read the same
pipeline analytics that power the app's Analytics pages: won/lost outcomes,
stage durations, and the stage-to-stage funnel.

All operations go through the developer API gateway — one endpoint, called by
`operationId`. If you haven't set up a key yet, start with the
[Developer API Overview](/developer-api/overview).

## Operations

### Reading pipelines (`READ` scope)

| operationId          | What it does                                                                                                                                                                                                                                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listPipelines`      | List the organization's deal pipelines with per-stage deal counts and values.                                                                                                                                                                                                                      |
| `listPipelineStages` | List a pipeline's stages in order (by `pipelineId`). Use a stage id with `createDeal`/`updateDeal`.                                                                                                                                                                                                |
| `getDeletionImpact`  | Preview what deleting a pipeline or stage affects: pass `targetKind` (`DEAL_PIPELINE`/`DEAL_STAGE`) + `targetId`, get back an `impactVersion` (hand it to the delete op), whether replacements are required, and the dependent deals. **Call this before `deletePipeline`/`deletePipelineStage`.** |

### Managing pipeline structure (`WRITE` scope)

| operationId             | What it does                                                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createPipeline`        | Create a deal pipeline (`title` required; optional `description` and initial `stages`). Created under your org.                                                                                                                                                                                                                                        |
| `updatePipeline`        | Update a pipeline's `title`/`description` (by `pipelineId`).                                                                                                                                                                                                                                                                                           |
| `addPipelineStages`     | Append stages to a pipeline. Returns the pipeline with its full ordered stage list.                                                                                                                                                                                                                                                                    |
| `updatePipelineStage`   | Update one stage (by `stageId`) — name, description, `isTerminal`/`terminalType`, `winProbability`. Only passed fields change.                                                                                                                                                                                                                         |
| `reorderPipelineStages` | Reorder a pipeline's stages (pass every stage id in the desired order).                                                                                                                                                                                                                                                                                |
| `deletePipeline`        | Delete a deal pipeline. Pass a `dependencyResolution` from `getDeletionImpact` — its `impactVersion` plus a disposition for every deal the pipeline still holds (empty if none). Each stage's deals are either reassigned to a replacement stage or **permanently deleted**, depending on which option you select — see the warning below. Owner-only. |
| `deletePipelineStage`   | Delete a single stage. Pass a `dependencyResolution` from `getDeletionImpact` (targetKind `DEAL_STAGE`) — `impactVersion` plus a disposition for any deals on it: a replacement stage, or the delete-all option. Owner-only.                                                                                                                           |

<Warning>
  **A `dependencyResolution` can delete deals, not just move them**

  When a stage still holds deals, `getDeletionImpact` returns the destination
  stages you can move them to **plus a synthetic "delete all deals in this
  stage" option**. Choosing that option **permanently deletes every deal on the
  stage — archived deals included — with no undo.**

  The two kinds of option come back in the same list, so any client that builds
  a `dependencyResolution` programmatically must tell them apart: a replacement
  stage id reassigns, the delete-all id destroys. Never pass an option straight
  through from `getDeletionImpact` without checking which one it is.
</Warning>

<Note>
  **Owner-only structure edits**

  Editing pipeline structure (`updatePipeline`, `addPipelineStages`,
  `updatePipelineStage`, `reorderPipelineStages`) requires the pipeline to be
  **owned** by your organization. A pipeline merely *shared* with you through
  a partnership can hold your deals, but its structure can only be changed by
  the owning org — otherwise the call returns `403 forbidden`.
</Note>

<Tip>
  **Finding a new pipeline's id**

  `createPipeline` returns your full pipeline list rather than just the new
  pipeline (names aren't unique and order isn't creation order). Call
  `listPipelines` first, create, then diff the ids — and use distinct titles
  if you create pipelines concurrently.
</Tip>

### Pipeline analytics (`ADMIN` scope)

Reporting reads over the same nightly snapshots as the web app's Analytics
pages — each response carries the `asOfDate` it was computed. Both take an
optional `period`: `SEVEN_DAYS` | `FOURTEEN_DAYS` | `THIRTY_DAYS` |
`YEAR_TO_DATE` (default `THIRTY_DAYS`).

| operationId               | What it does                                                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getPipelineAnalytics`    | Per-pipeline outcome analytics for a period — won/lost/active deal counts, average stage duration, current stage mix.                                                 |
| `listPipelineTransitions` | Stage-to-stage deal movement (the funnel) for a period, optionally narrowed to one `pipelineId` — per transition: deal counts, source-stage exits, won/lost outcomes. |

<Warning>
  **Rate-limited**

  Analytics operations are rate-limited per key. Exceeding the limit returns
  `429 rate_limited` with a `Retry-After` header — back off and retry after
  that many seconds. Team-level analytics (per-agent activity and outcomes)
  live in the [Team API](/developer-api/team).
</Warning>

## Example

Read the funnel for one pipeline over the last 14 days:

```bash theme={null}
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listPipelineTransitions", "variables": { "pipelineId": "PIPELINE_ID", "period": "FOURTEEN_DAYS" } }'
```

Full variable schemas, response shapes, and worked examples for every
operation are available from the
[discovery endpoint](/developer-api/overview#discovering-operations).