Introduction

A curated REST surface over the Blue platform - RPC and resource-style endpoints over the same data and auth as GraphQL.

The Blue REST API is a curated HTTP surface over the same platform that powers the app, the GraphQL API, and the MCP server. It exposes the operations most integrations reach for - records, workspaces, lists, custom fields, comments, webhooks, and more - as plain JSON over standard HTTP verbs, so you can call Blue from any language with an HTTP client and no GraphQL tooling.

The base URL is https://rest.blue.app/v1. Every endpoint lives under that prefix.

curl https://rest.blue.app/v1/list-workspaces \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "blue-org-id: YOUR_ORG_ID" \
  -d '{}'

Two ways to call

Every operation is reachable two ways - both hit the same handlers and return the same shapes, so you can mix styles freely.

RPC is the complete surface: a POST /v1/<operation> whose JSON body is the operation’s input. Every operation is available this way, named after the action it performs.

POST /v1/list-records
POST /v1/create-record
POST /v1/move-record

Resource-style is a REST-idiomatic layer over the core resources - records, workspaces, and lists - using HTTP verbs and path parameters.

GET    /v1/records
GET    /v1/records/{id}?workspaceId=...
POST   /v1/records
PATCH  /v1/records/{id}
DELETE /v1/records/{id}?workspaceId=...
POST   /v1/records/{id}/move

Use whichever fits your client. Resource-style reads cleanly for CRUD on records, workspaces, and lists; RPC covers everything else - tags, checklists, automations, reports, search, and the rest. See Making Requests for both styles in depth.

What’s covered

The REST API spans 50+ operations across the platform:

records, workspaces, lists, tags, custom fields, comments, checklists, users, activity, documents, saved views, dependencies, reports, charts, dashboards, form fields, forms, automations, webhooks, files, and search.

Authentication in one line

Every request carries two headers: a Bearer personal access token and a blue-org-id naming the organization to act in. These are the same tokens the GraphQL API and MCP server use - create one in Blue’s settings. See Authentication for the full model.

Responses

Responses are plain JSON. Fields come back untrimmed - null and empty values are present rather than omitted - so object shapes stay stable across responses and you can rely on a key existing whether or not it holds a value.

List operations page with skip and limit; see Pagination. Errors return a JSON { "error": ... } body with a standard HTTP status; see Errors & Rate Limits.

REST or GraphQL?

The REST API is a deliberately curated subset - the high-value operations, shaped for HTTP. The GraphQL API exposes the full platform schema: every type, every field, real-time subscriptions, and selection sets that return exactly the fields you ask for. Both share the same data and the same authentication, so you can use them side by side.

  • Reach for REST when you want a quick HTTP call, a fixed JSON shape, or a language without good GraphQL tooling.
  • Reach for GraphQL when you need a field or operation REST doesn’t cover, want to shape the response, or need subscriptions.

Explore the API

The full machine-readable spec is published as OpenAPI at https://rest.blue.app/v1/openapi.json. The interactive API Reference in the sidebar is generated from it - browse every operation, its inputs, and a live request builder there.

Next steps