Overview

The Blue Reacher API: base URL, authentication, conventions, every reference group with the scope it needs, errors and rate limits.

The Blue Reacher API is JSON over HTTPS. Any tool that can make an HTTP request can call it.

Base URL

https://api.bluereacher.com/v1

Every example in this reference uses full URLs built from this base.

Authentication

Every route except POST /v1/send takes an OAuth access token in the Authorization header:

Authorization: Bearer <ACCESS_TOKEN>

Your app gets tokens when a Blue Reacher user installs it. Access tokens last 24 hours and refresh tokens one year. The flow is on Authentication, the token layout on Token format, and the permissions on Scopes.

Each route declares the scope it needs. A token without it answers 403.

Conventions

Workspaces. Most routes take a workspace_id, in the body or the query string. A workspace must belong to the installer.
Ids are numbers. A message's message_id is the same number as a string.
Pagination. List routes take page (1-based, default 1) and limit (clamped to 1 to 200, default 50). Out-of-range values are normalised, not rejected, and the response's pagination object reports what was applied:

{
  "total": 450,
  "page": 1,
  "limit": 50,
  "max_limit": 200,
  "total_pages": 9,
  "requested_page": null,
  "requested_limit": null,
  "normalized": false
}

Phone numbers carry the country code, for example +15551234567.
Bodies are JSON. Send Content-Type: application/json on requests with a body.
Envelope. Every success response has "success": true and the result under data. Lists put the rows in data and the paging under pagination.

Reference

Group	Scopes	What it covers
OAuth	None	Install URL, code exchange, refresh
Probe	None	`GET /v1/integration/me`, a wiring test
Workspaces	`workspaces.*`	Sub-accounts, inbound webhook settings
Contacts	`contacts.*`	Contacts, tags on a contact, notes, DND, Check iMessage
Tags	`contacts.*`	The workspace tag library
Custom fields	`contacts.*`	Custom field definitions
Devices	`devices.*`	Every line in the account
Send a message	Dashboard key	`POST /v1/send`: send a text message with one header (API keys)
Messages	`messages.*`	Send, list, status, reactions, edit, unsend, notify anyway, scheduled sends
Conversations	`conversations.*`	The inbox, a contact's thread, read, starred and archived state
Group chats	`groups.*`	iMessage groups
Calls	`calls.*`	Place and end calls, missed calls, routing, history
Lead forms	`lead_forms.*`	Hosted forms and their submissions
Automations	`automations.*`	Workflows, templates, activation, contacts in a workflow
Opportunities	`opportunities.*`	Pipelines, stages and deals
Tasks	`tasks.*`	To-dos with due dates and reminders
Subaccount admins	`subaccount_admins.*`	Team members and their workspace access
AI agents	`ai_agents.*`	The agents that hold conversations with contacts

Errors

Errors return "success": false and a message:

{
  "success": false,
  "message": "Invalid or expired access token."
}

Status	Meaning
400	Validation. The message names the field or rule.
401	The token is missing, invalid or expired. Refresh it.
403	The token lacks the scope. The message lists what was granted.
404	Not found, or not owned by the installer.
409	Conflict, including a send to a contact with outbound DND on.
429	Rate limited. `error` is `RateLimitExceeded`.
5xx	Server or provider failure. 502 is retryable. 504 means the line did not answer in time.

The full table, the upper-case codes in message text and the retry rules are on Errors.

Rate limits

By default an app gets 100 requests per 10 seconds and 200,000 per UTC day, per installation. Sends are limited to 30 per 15 minutes per workspace. Read the X-RateLimit-* headers and honour Retry-After on a 429. Details on Rate limits.

OpenAPI

The whole reference is also published as a spec at https://docs.bluereacher.com/openapi.json. See OpenAPI spec.