Introduction

Get started with the Blue API — a single GraphQL endpoint for everything in your Blue organization, authenticated with personal access tokens.

The Blue API is a single GraphQL endpoint that exposes the same data and operations you use in the Blue app: organizations, workspaces, records, lists, custom fields, comments, automations, and more. Blue is a process-management platform used by 19,000+ organizations, and anything you can do in the UI you can drive programmatically.

GraphQL means one endpoint, a typed schema you can introspect, and responses that return exactly the fields you ask for. If you’re new to GraphQL, the graphql.org learning guide is a good primer.

Base endpoint

All requests are POST to a single URL:

https://api.blue.app/graphql

Real-time subscriptions use the WebSocket endpoint wss://api.blue.app/graphql. See Realtime for the subscription protocol.

Authentication in one minute

The API authenticates with a personal access token (PAT) — a Token ID and a Secret you generate from your profile’s API tab. You send them as request headers, along with the organization (and, for some operations, the workspace) you want to act in:

HeaderRequiredDescription
blue-token-idYesYour token ID (prefixed pat_).
blue-token-secretYesYour token secret. Shown once at creation — store it securely.
blue-org-idMost operationsThe organization ID or slug to act in.
blue-workspace-idSome operationsThe workspace ID or slug, when an operation is scoped to one.

Header names are case-insensitive. The secret is hashed with bcrypt on our side, so it can never be recovered after creation — treat it like a password.

Keep your secret safe

Anyone with your Token ID and Secret can read and modify your organization’s data. Store the secret in a secrets manager, never in client-side code or version control.

See Authentication for how to create a token and find your organization and workspace IDs, and Making Requests for full curl, Python, and Node examples.

Quick start

Once you have a token, this query lists the workspaces in an organization. Workspaces are Workspace objects in the API, queried with the workspaceList query.

curl -X POST https://api.blue.app/graphql \
  -H "Content-Type: application/json" \
  -H "blue-token-id: YOUR_TOKEN_ID" \
  -H "blue-token-secret: YOUR_TOKEN_SECRET" \
  -H "blue-org-id: YOUR_ORG_ID" \
  -d '{
    "query": "query MyWorkspaces($filter: ProjectListFilter!) { workspaceList(filter: $filter) { items { id name updatedAt } } }",
    "variables": { "filter": { "companyIds": ["company_123"] } }
  }'

The same operation as a named GraphQL document:

query MyWorkspaces {
  workspaceList(filter: { companyIds: ["company_123"] }) {
    items {
      id
      name
      updatedAt
    }
  }
}

companyIds accepts organization IDs or slugs. The response returns the requested fields and nothing else:

{
  "data": {
    "workspaceList": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "name": "Product Roadmap",
          "updatedAt": "2026-05-20T14:32:11.000Z"
        }
      ]
    }
  }
}

Want to experiment without writing code first? Open the GraphQL Playground in your browser to run authenticated queries and browse the full schema.

What you’ll learn

The rest of this section covers everything you need before working with specific resources:

  1. Authentication — create a personal access token and find your organization and workspace IDs.
  2. Making Requests — send queries, mutations, and variables over curl, Python, and Node.
  3. Capabilities — what the API can do, including schema introspection.
  4. Rate Limits — request limits by plan and the headers that report your remaining quota.
  5. Upload Files — attach documents and images to records and comments.
  6. GraphQL Playground — explore and run operations interactively in the browser.
  7. Error Codes — the codes returned in the errors array and what each one means.

What you can build

  • Sync records both ways. Create and update records (Record objects) from external systems, and read them back to keep another database, spreadsheet, or warehouse in step.
  • Drive workflows from external events. Turn inbound forms, webhooks, or emails into records, set custom field values, and move records between lists as work progresses.
  • Connect Blue to your stack. Push data from a CRM, ERP, or support tool into the right workspace, and surface Blue data in your own dashboards.
  • React in real time. Subscribe over WebSocket to record, comment, and file events to update integrations the moment something changes — see Realtime.