nodestash
Pipelines

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.

POST
/pipelines

Authorization

apiKey
AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://api.nodestash.io/v1/pipelines" \  -H "Content-Type: application/json" \  -d '{    "name": "Sales Pipeline",    "description": "Main sales pipeline for inbound leads",    "stages": [      {        "name": "Qualification",        "position": 0,        "type": "open"      },      {        "name": "Proposal",        "position": 1,        "type": "open"      },      {        "name": "Negotiation",        "position": 2,        "type": "open"      },      {        "name": "Closed Won",        "position": 3,        "type": "won"      },      {        "name": "Closed Lost",        "position": 4,        "type": "lost"      }    ]  }'
{
  "data": {
    "id": "pp_8rT4mK9pQsVwXyZaB2cD4",
    "type": "pipeline",
    "attributes": {
      "id": "pp_8rT4mK9pQsVwXyZaB2cD4",
      "name": "Sales Pipeline",
      "description": "Main sales pipeline for inbound leads",
      "is_default": false,
      "stages": [
        {
          "id": "ps_1aB2cD3eF4gH5iJ6kL7m",
          "name": "Qualification",
          "position": 0,
          "type": "open",
          "created_at": "2026-02-01T10:00:00Z",
          "updated_at": "2026-02-01T10:00:00Z"
        },
        {
          "id": "ps_2bC3dE4fG5hI6jK7lM8n",
          "name": "Proposal",
          "position": 1,
          "type": "open",
          "created_at": "2026-02-01T10:00:00Z",
          "updated_at": "2026-02-01T10:00:00Z"
        },
        {
          "id": "ps_4kT9mN2qRsYvAzCeB2cD4",
          "name": "Negotiation",
          "position": 2,
          "type": "open",
          "created_at": "2026-02-01T10:00:00Z",
          "updated_at": "2026-02-01T10:00:00Z"
        },
        {
          "id": "ps_5dE6fG7hI8jK9lM1nO2p",
          "name": "Closed Won",
          "position": 3,
          "type": "won",
          "created_at": "2026-02-01T10:00:00Z",
          "updated_at": "2026-02-01T10:00:00Z"
        },
        {
          "id": "ps_6eF7gH8iJ9kL1mN2oP3q",
          "name": "Closed Lost",
          "position": 4,
          "type": "lost",
          "created_at": "2026-02-01T10:00:00Z",
          "updated_at": "2026-02-01T10:00:00Z"
        }
      ],
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  },
  "meta": {
    "request_id": "req_2bC3dE4fG5hI6jK7lM8n"
  }
}
{
  "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": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Update a deal

Partially updates a deal. Only the provided fields are changed — omitted fields remain untouched. `custom_fields` are **merged** with existing values (not replaced). When `stage_id` is changed, the stage must belong to the deal's current pipeline. `closed_at` is automatically set when moving to a `won` or `lost` stage and cleared when moving back to an `open` stage.

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.