nodestash
Pipelines

Add a stage to a pipeline

Adds a new stage to an existing pipeline. The `position` determines where the stage appears in the pipeline order.

POST
/pipelines/{id}/stages

Authorization

apiKey
AuthorizationBearer <token>

API key from your nodestash dashboard. Pass as a Bearer token in the Authorization header.

In: header

Path Parameters

id*string

Pipeline ID (prefixed with pp_).

Match^pp_

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.nodestash.io/v1/pipelines/pp_8rT4mK9pQsVwXyZaB2cD4/stages" \  -H "Content-Type: application/json" \  -d '{    "name": "Contract Review",    "position": 3,    "type": "open"  }'
{
  "data": {
    "id": "ps_7fG8hI9jK1lM2nO3pQ4r",
    "type": "pipeline_stage",
    "attributes": {
      "id": "ps_7fG8hI9jK1lM2nO3pQ4r",
      "name": "Contract Review",
      "position": 3,
      "type": "open",
      "created_at": "2026-02-10T11:00:00Z",
      "updated_at": "2026-02-10T11:00:00Z"
    }
  },
  "meta": {
    "request_id": "req_4dE5fG6hI7jK8lM9nO1p"
  }
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid Authorization header"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Contact not found"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Create a new pipeline

Creates a new pipeline with stages in the authenticated workspace. The `stages` array must contain at least one stage of type `won` and one of type `lost`. Stages are ordered by their `position` field.

Delete a pipeline

Permanently deletes a pipeline and all its stages. Cannot delete the last remaining pipeline in a workspace. Cannot delete a pipeline that still has deals — move or delete deals first.