# Stage Checklist Pipelines

> REST reference for graph8 Stage Checklist v2 pipelines — multi-stage workflows with evidence requirements and channel scripts

Source: https://docs.graph8.com/developers/pipelines/

A Stage Checklist pipeline is a multi-stage workflow with per-stage **evidence requirements** (e.g. "budget confirmed", "decision-maker identified") and **channel scripts** (call, email, LinkedIn) tied to each stage. Distinct from deal pipelines, which are the simple stage-list deals progress through.

> **Tip:**
> For deal pipelines (the lightweight stages your deals sit in), use `/api/v1/deals/pipelines` — documented under [Deals](https://docs.graph8.com/developers/deals/). This page covers the heavier Stage Checklist v2 surface.

> **Note: Auth**
> Every call needs `Authorization: Bearer $G8_API_KEY`. The `X-Org-Id` is bound to the key automatically. [Get a key in 30 seconds →](https://docs.graph8.com/developers/authentication/)

## 30-second start

List your Stage Checklist pipelines:

**cURL**

```bash
curl 'https://be.graph8.com/api/v1/pipelines' \
  -H "Authorization: Bearer $G8_API_KEY"
```

**TypeScript**

```typescript
import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data } = await g8.pipelines.list();
console.log(data); // → StagePipeline[] with stages + evidence + channel scripts
```

**CLI**

```bash
g8 list-stage-pipelines
```

**MCP**

Ask your agent: *"List my stage-checklist pipelines"* → tool: `g8_list_pipelines`.

## Quick reference

| Endpoint | Method | Purpose |
|---|---|---|
| `/pipelines` | GET | List pipelines |
| `/pipelines` | POST | Create |
| `/pipelines/{id}` | GET | Get a pipeline with all stages |
| `/pipelines/{id}` | PUT | Update metadata (name, target) |
| `/pipelines/{id}` | DELETE | Delete (no deals must reference) |
| `/pipelines/evidence-library` | GET | Canonical 8-key evidence library |
| `/pipelines/{id}/stages` | POST | Add a stage |
| `/pipelines/{id}/stages/{stage_id}` | PUT | Update a stage |
| `/pipelines/{id}/stages/{stage_id}` | DELETE | Delete a stage |
| `/pipelines/{id}/stages/reorder` | PUT | Reorder stages |
| `/pipelines/suggest` | POST | AI-suggested pipeline from org context |
| `/pipelines/from-suggestion` | POST | Promote a suggestion into a real pipeline |

## Pipeline shape

```typescript
{
  id: "pip_xyz",
  name: "Enterprise Outbound",
  target: "Land 5 new logos in Q3",
  is_default: false,
  stages: [
    {
      id: "stg_discovery",
      name: "Discovery",
      position: 0,
      required_elements: ["budget_confirmed", "timeline_known"],
      recommended_elements: ["competitor_landscape"],
      channel_scripts: {
        email: "Hi {{first_name}}...",
        call: "Hello, calling about..."
      },
      color: "#00CAEB",
      stage_type: "qualification"
    },
    { id: "stg_demo", name: "Demo", position: 1, ... }
  ]
}
```

## Evidence library

The canonical 8 evidence keys (returned by `GET /pipelines/evidence-library`) cover the typical qualification criteria:

| Key | Label |
|---|---|
| `budget_confirmed` | Budget confirmed |
| `timeline_known` | Decision timeline known |
| `decision_maker_identified` | Decision maker identified |
| `pain_point_validated` | Pain point validated |
| `competitor_landscape` | Competitor landscape understood |
| `success_criteria_agreed` | Success criteria agreed |
| `legal_review_started` | Legal review started |
| `commercial_terms_aligned` | Commercial terms aligned |

Use these in `required_elements` / `recommended_elements` on each stage.

## Create

```bash
# Default templated stages
POST /api/v1/pipelines
{ "name": "Enterprise Outbound", "target": "Land 5 new logos in Q3" }

# Or blank
POST /api/v1/pipelines
{ "name": "Custom flow", "blank": true }
```

## Update

```bash
PUT /api/v1/pipelines/{pipeline_id}
{ "name": "Renamed", "target": "Updated target" }
```

## Stages

```bash
POST /api/v1/pipelines/{pipeline_id}/stages
{
  "name": "Discovery",
  "position": 0,
  "required_elements": ["budget_confirmed"],
  "channel_scripts": { "email": "Hi {{first_name}}..." }
}

PUT /api/v1/pipelines/{pipeline_id}/stages/{stage_id}
{ "color": "#00CAEB", "recommended_elements": ["competitor_landscape"] }

DELETE /api/v1/pipelines/{pipeline_id}/stages/{stage_id}

PUT /api/v1/pipelines/{pipeline_id}/stages/reorder
{ "stage_ids": ["stg_qual", "stg_demo", "stg_negotiation", "stg_close"] }
```

## AI suggestion

```bash
POST /api/v1/pipelines/suggest
# Returns: { data: { suggestion_id, name, target, stages: [...], rationale } }

POST /api/v1/pipelines/from-suggestion
{ "suggestion_id": "sug_abc123", "name": "PLG Path" }
```

The suggestion engine reads the org's Studio context (brand brief, ICPs, personas, messaging house — see [Studio Context](https://docs.graph8.com/developers/sdk/#studio-context)) and proposes a pipeline tailored to the org's GTM motion. Apply via `from-suggestion`, optionally overriding the name / target.

## Credit costs

All endpoints are free. AI suggestion runs an LLM internally — that consumes credits implicitly (~50-100 per suggestion, depending on context size).

## Errors

| Status | Cause | Fix |
|---|---|---|
| `401` | Missing or invalid `Authorization: Bearer` header | [Get a key](https://docs.graph8.com/developers/authentication/) |
| `402` | Out of credits (waterfall enrichment, AI generation, voice minutes) | Top up in **Settings → Billing**, or switch to Platform |
| `404` | Resource ID doesn't exist | List first to verify the ID |
| `422` | Validation error in request body | Inspect `error.message` + `error.field` in the response |
| `429` | Rate limit (50 rps per org) | Backoff per `Retry-After` header. See [Rate Limits](https://docs.graph8.com/developers/rate-limits/) |
| `5xx` | graph8 error | Retry with exponential backoff (5s → 30s → 120s) |

The full error envelope shape: `{ "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }`. Include the `request_id` in any support ticket. See [Errors](https://docs.graph8.com/developers/errors/) for the canonical reference.

## See also

- [SDK pipelines methods](https://docs.graph8.com/developers/sdk/#stage-checklist-pipelines)
- [CLI stage-pipeline commands](https://docs.graph8.com/developers/cli/#stage-checklist-pipelines)
- [MCP pipeline tools](https://docs.graph8.com/developers/mcp/#pipelines-stage-checklist-v2--12-tools)
- [Deals](https://docs.graph8.com/developers/deals/) — for deal pipelines (different surface)