# CLI Pipelines (Deal Pipelines)

> Create and manage deal pipelines — the lightweight stage lists that deals progress through in graph8

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

Deal pipelines define the ordered stages a deal moves through (e.g. Prospecting → Discovery → Proposal → Closed Won). These endpoints let you create, update, and stage-manage pipelines, look up the shared evidence library, and generate AI-suggested pipelines from your org's Studio context.

> **Note:**
> This page covers **deal pipelines** — the stage lists your deals sit in. For Stage Checklist v2 pipelines (heavier evidence-requirement workflows with channel scripts), see [Stage Checklist Pipelines](https://docs.graph8.com/developers/pipelines/).

---

## List Pipelines

`GET /pipelines`

Returns all pipelines for the org as a `PipelineResponse[]` array. Each pipeline includes v2 stage fields (position, color, `stage_type`, `required_elements`, `recommended_elements`, `channel_scripts`).

### Example

**cURL**

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

---

## Get Pipeline

`GET /pipelines/{pipeline_id}`

Returns a single `PipelineResponse` with all stages.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pipeline_id` | string | Pipeline ID |

### Example

**cURL**

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

---

## Get Evidence Library

`GET /pipelines/evidence-library`

Returns the 8 canonical evidence keys available for use in `required_elements` and `recommended_elements` on any stage.

### Example

**cURL**

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

### Response

```json
{
  "data": [
    { "key": "pain_identified", "label": "Pain identified" },
    { "key": "impact_quantified", "label": "Impact quantified" },
    { "key": "stakeholder_mapped", "label": "Stakeholder mapped" },
    { "key": "decision_process_known", "label": "Decision process known" },
    { "key": "timeline_known", "label": "Timeline known" },
    { "key": "commercial_posture_known", "label": "Commercial posture known" },
    { "key": "next_step_scheduled", "label": "Next step scheduled" },
    { "key": "risk_or_blocker_logged", "label": "Risk/blocker logged" }
  ]
}
```

---

## Create Pipeline

`POST /pipelines`

Creates a new pipeline. Returns `201 Created`.

### Request Body

All fields are optional.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | string | — | Display name for the pipeline |
| `target` | string | `"prospects_revenue"` | Pipeline target — one of `prospects_revenue`, `prospects_meeting`, or `customers_revenue` |
| `blank` | boolean | `false` | When `true`, the pipeline is created with 2 placeholder stages instead of the default template |

### Example

**cURL**

```bash
# Templated pipeline
curl -X POST "https://be.graph8.com/api/v1/pipelines" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Pipeline",
    "target": "prospects_revenue",
    "blank": false
  }'

# Blank pipeline (2 placeholder stages)
curl -X POST "https://be.graph8.com/api/v1/pipelines" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Pipeline",
    "blank": true
  }'
```

---

## Update Pipeline

`PUT /pipelines/{pipeline_id}`

Updates pipeline metadata. All fields are optional — send only the fields you want to change.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pipeline_id` | string | Pipeline ID |

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New display name |
| `target` | string | New target — one of `prospects_revenue`, `prospects_meeting`, or `customers_revenue` |
| `set_default` | boolean | When `true`, marks this pipeline as the org default |

### Example

**cURL**

```bash
curl -X PUT "https://be.graph8.com/api/v1/pipelines/pip_abc123" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed Pipeline",
    "set_default": false
  }'
```

---

## Add Stage

`POST /pipelines/{pipeline_id}/stages`

Adds a new stage to an existing pipeline. Returns `201 Created`.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pipeline_id` | string | Pipeline ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | **Yes** | Stage display name |
| `probability` | integer | No (default `0`) | Win probability percentage for this stage (0–100) |
| `stage_type` | string | No (default `"open"`) | Stage type |
| `color` | string | No | Hex color string (e.g. `"#6B7280"`) |
| `required_elements` | array of strings | No | Evidence keys that must be met to advance past this stage. Values must come from `GET /pipelines/evidence-library`. |
| `recommended_elements` | array of strings | No | Evidence keys that are recommended but not required |
| `channel_scripts` | object | No | Per-channel outreach scripts. Keys must be one of `call`, `email`, or `linkedin`. |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/pipelines/pip_abc123/stages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discovery",
    "probability": 30,
    "stage_type": "open",
    "color": "#6B7280",
    "required_elements": ["pain_identified"],
    "recommended_elements": [],
    "channel_scripts": {
      "call": "Hi, I am calling to learn more about...",
      "email": "Hi {{first_name}}, reaching out because...",
      "linkedin": "Hi {{first_name}}, noticed you..."
    }
  }'
```

---

## Update Stage

`PUT /pipelines/{pipeline_id}/stages/{stage_id}`

Partial update — send only the fields to change. All fields are optional (same set as Add Stage).

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pipeline_id` | string | Pipeline ID |
| `stage_id` | string | Stage ID |

### Request Body

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Stage display name |
| `probability` | integer | Win probability percentage (0–100) |
| `stage_type` | string | Stage type |
| `color` | string | Hex color string |
| `required_elements` | array of strings | Evidence keys required to advance |
| `recommended_elements` | array of strings | Recommended evidence keys |
| `channel_scripts` | object | Per-channel scripts. Keys: `call`, `email`, `linkedin` |

### Example

**cURL**

```bash
curl -X PUT "https://be.graph8.com/api/v1/pipelines/pip_abc123/stages/stg_xyz" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "probability": 50,
    "color": "#3B82F6"
  }'
```

---

## Reorder Stages

`PUT /pipelines/{pipeline_id}/stages/reorder`

Sets the full ordered list of stage IDs for a pipeline. All existing stage IDs must be included.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pipeline_id` | string | Pipeline ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `stage_ids` | array of strings | **Yes** | Complete ordered list of all stage IDs for this pipeline |

### Example

**cURL**

```bash
curl -X PUT "https://be.graph8.com/api/v1/pipelines/pip_abc123/stages/reorder" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_ids": ["stg_prospecting", "stg_discovery", "stg_proposal", "stg_closed"]
  }'
```

---

## Suggest Pipeline (AI)

`POST /pipelines/suggest`

Generates an AI-suggested pipeline tailored to your org's GTM motion. Reads Studio context (brand brief, ICPs, messaging house, etc.) to craft a proposal. Returns the suggestion but does **not** persist it — use `POST /pipelines/from-suggestion` to create the pipeline.

> **Caution:**
> This endpoint consumes credits. The suggestion runs an LLM internally against your Studio context.

### Request Body

All fields are optional.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `target` | string | — | Pipeline target to optimise for — one of `prospects_revenue`, `prospects_meeting`, or `customers_revenue` |
| `motion_hint` | string | — | Free-text hint for the sales motion (e.g. `"PLG"`, `"enterprise outbound"`) |
| `use_brief_only` | boolean | `true` | When `true`, reads only the Campaign Intelligence Brief (faster, cheaper). Set to `false` to read all 43 Studio docs. |

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/pipelines/suggest" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "prospects_revenue",
    "motion_hint": "PLG",
    "use_brief_only": true
  }'
```

---

## Create Pipeline from Suggestion

`POST /pipelines/from-suggestion`

Persists a previously returned `PipelineSuggestion` as a real pipeline. Returns `201 Created` with the saved pipeline.

### Request Body

Pass the full `PipelineSuggestion` object returned by `POST /pipelines/suggest` as the request body.

### Example

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/pipelines/from-suggestion" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PLG Inbound",
    "target": "prospects_revenue",
    "stages": [
      {
        "name": "Trial Started",
        "probability": 20,
        "stage_type": "open",
        "color": "#6B7280",
        "required_elements": ["pain_identified"],
        "recommended_elements": ["next_step_scheduled"],
        "channel_scripts": {}
      }
    ]
  }'
```

---

## See also

- [Stage Checklist Pipelines](https://docs.graph8.com/developers/pipelines/) — heavier evidence-requirement pipelines with channel scripts and a v2 stage model
- [Deals](https://docs.graph8.com/developers/deals/) — move deals between pipeline stages