Skip to content

Pipelines and stages

Method & path Scope Notes
GET /pipelines records:read With stages. ?status=archived or all
GET /pipelines/:id records:read One pipeline with stages
GET /pipelines/:id/board records:read Stages with their deals, counts and totals. ?q= filters by deal name
POST /pipelines pipelines:manage { name, description?, stages?: [{ name, probability?, outcome? }] } → 201
PATCH /pipelines/:id pipelines:manage { name?, description?, isDefault?, status?, position? }
DELETE /pipelines/:id pipelines:manage Only without deals (422 PIPELINE_NOT_EMPTY; archive instead)
POST /pipelines/:id/stages pipelines:manage { name, probability?, outcome?="open", position? }
PATCH /stages/:id pipelines:manage { name?, probability?, outcome? }
DELETE /stages/:id?moveDealsTo=<stageId> pipelines:manage With deals and no target → 422 STAGE_NOT_EMPTY
PUT /pipelines/:id/stages/order pipelines:manage { stageIds: [...] }, exactly the pipeline’s stages

Pipeline: { id, name, description, position, isDefault, status, stages: Stage[], createdAt, updatedAt } (stages by position).

Stage: { id, pipelineId, name, position, probability (0–100), outcome: "open"|"won"|"lost" }.

  • Every pipeline has at least one open stage and exactly one won stage; any number of lost stages. Breaking this → 422 PIPELINE_INVALID with details.reason.
  • Exactly one default pipeline per account; the first one becomes default. The default pipeline cannot be deleted or archived (422 DEFAULT_PIPELINE): make another one default first.
  • A pipeline created without stages gets Lead 10 · Qualified 25 · Proposal 50 · Negotiation 75 (open) · Won 100 (won) · Lost 0 (lost). A stage without probability gets 10 (open), 100 (won) or 0 (lost).
  • Changing a stage’s outcome moves its deals’ closedAt with it (closed outcomes set it where missing; open clears it and lostReason).
  • On the Free plan an account has one pipeline: POST /pipelines answers 402 PLAN_LIMIT_REACHED.
Terminal window
curl -s -X POST https://api.mety.ai/api/v1/pipelines \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: pipeline-partners" \
-d '{
"name": "Partners",
"stages": [
{ "name": "Intro", "probability": 10 },
{ "name": "Pilot", "probability": 50 },
{ "name": "Signed", "outcome": "won" },
{ "name": "Dropped", "outcome": "lost" }
]
}'
Terminal window
curl -s "https://api.mety.ai/api/v1/pipelines/$PIPELINE_ID/board" -H "Authorization: Bearer $METY_KEY"
{
"data": {
"pipeline": { "id": "…", "name": "Sales", "…": "…" },
"columns": [
{
"stage": { "id": "…", "name": "Proposal", "outcome": "open", "probability": 50, "…": "…" },
"deals": [ { "id": "…", "name": "Acme · annual licence", "amountCents": 480000, "currency": "EUR", "…": "…" } ],
"count": 1,
"totals": [{ "currency": "EUR", "amountCents": 480000, "mrrCents": 40000 }]
}
]
}
}

Active deals only, up to 200 cards per column, in position order. Cards (DealCard) are deals without description, customFields and externalRefs. Totals are per currency.