Real-time (Subscriptions)

Blue’s GraphQL API exposes a large type Subscription root that delivers real-time push updates over a WebSocket transport (graphql-ws) at wss://api.blue.cc/graphql — the same URL as the HTTP GraphQL endpoint. This section explains how to open and authenticate a subscription, then documents every operation grouped by domain: entity change-feeds (records, projects, comments, custom fields, files, activity), presence and notifications, and progress streams for long-running jobs.

Authentication uses the same credentials as HTTP requests, passed through graphql-ws connectionParams at connection init (a Personal Access Token or a Bearer JWT). The same permission checks apply: subscribing succeeds, but you only receive events for the records and projects you are allowed to see.

How subscriptions work

A subscription is a long-lived GraphQL operation. You open one WebSocket connection, send one or more subscription { … } operations over it, and the server streams a result every time a matching change happens server-side. The connection stays open until you close it or the socket drops.

Three things are consistent across the whole section:

• One endpoint, one protocol. All subscriptions run over graphql-ws at wss://api.blue.cc/graphql. There is no separate subscription path. See Connect & Authenticate.
• Auth at connect, in connectionParams. Credentials ride in the graphql-ws connection-init payload, not in per-operation arguments. An unauthenticated handshake is rejected before any subscription starts.
• Permission gating per event. Each delivered event is filtered against your permissions. You can subscribe broadly (e.g. all records in a workspace) and still only receive the changes you can see.

The entity-payload shape

Most subscriptions are change-feeds for an entity (a record, project, comment, custom field, file, and so on). They share one payload shape, so once you can read one you can read them all:

subscription OnRecordChange {
  subscribeToTodo(projectId: "project_123") {
    mutation # CREATED | UPDATED | DELETED
    node {
      # the entity in its new state (null on DELETED)
      id
      title
      done
    }
    previousValues {
      # the entity's prior state (present on UPDATED/DELETED)
      title
      done
    }
    updatedFields # [String] — names of the fields that changed on UPDATE
  }
}

MutationType

enum MutationType {
  CREATED
  UPDATED
  DELETED
}

Pages in this section

Start with the transport/auth primer, then jump to the domain you need. Each page documents its subscriptions, their filter inputs, and the exact payload type they return.

Product nouns to schema types

Subscription names use the schema type names, not the UI words. The mapping:

Deprecated subscriptions

Three subscriptions remain in the schema for backward compatibility but should not be used in new code. Each is omitted from this reference in favor of its replacement: