API

Use the application programming interface (API) to build integrations that read and change workspace data. The API uses GraphQL and includes a playground for testing queries.

Authentication

Generate a Personal Access Token under Account > API. Select Generate Token, then copy the Token ID and Secret.

The token belongs to your account and has the same permissions as you. Use blue-org-id to select the organization for a request.

Add blue-workspace-id when an operation needs explicit workspace context.

The token secret is shown only once. Store it securely. Anyone with both token values can call the API with your permissions. Revoke unused tokens under Account > API.

Blue-hosted request example

The following request uses the Blue-hosted GraphQL endpoint. For another deployment, use the endpoint supplied by its operator. Keep the authentication header names unchanged.

curl 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_OR_SLUG' \
  --data '{"query":"query { __typename }"}'

Rate limiting

Blue applies separate one-minute limits to each token, user, and organization. Each request counts against all applicable limits.

The response headers show the layer that is closest to its limit.

If you exceed the limit, the API returns HTTP 429 Too Many Requests. The Retry-After header specifies how many seconds to wait.

• Check the X-RateLimit-Remaining response header on each request.
• Reduce request frequency as the remaining quota decreases.
• Wait for the Retry-After period before retrying a 429 response.
• Batch related reads when possible. One multi-record query uses less quota than multiple single-record queries.

Plan limits

Request quotas depend on the organization’s plan. See Billing for Blue-hosted quotas. Enterprise customers can request increased quotas through Help & Support.