# Auth.md

## Authenticating with Blue Reacher

Blue Reacher is a B2B iMessage platform. It sends blue-bubble iMessages, with
automatic RCS then SMS fallback, from a customer's CRM across their whole
funnel. No A2P 10DLC registration is required, because iMessage is not carrier
SMS.

This file is for autonomous agents. If you are a person, the human version is
at https://docs.bluereacher.com.

## Getting a key

API keys are per customer and self-served. A human with a Blue Reacher account
generates one in the dashboard. Keys look like `brk_live_...` (test keys `brk_test_...`).

There is no public sandbox key and no self-registration endpoint. An agent
cannot provision itself an account. If you are acting for someone who does not
have one yet, send them to https://bluereacher.com/book.

## Authenticating

Send the key as a bearer token on every request:

```
Authorization: Bearer brk_live_your_key
Content-Type: application/json
```

Base URL: `https://api.bluereacher.com/v1`

## What you can call

- `POST https://api.bluereacher.com/v1/messages`  Sends a message over iMessage with automatic SMS fallback. Drip (default) inserts into the paced pipeline and delivers inside the org-local send window; instant dispatches immediately from an online line. Targets one recipient, an existing group thread, or 2 to 25 numbers as a new group iMessage. Attach up to 10 media URLs, and add native screen or bubble effects on instant sends.
- `POST https://api.bluereacher.com/v1/voice-memos`  Fetches your audio by URL (up to 25 MB, mp3/m4a/wav/aac), converts it to Apple's native voice-bubble format when possible, and falls back to a media attachment otherwise.
- `GET https://api.bluereacher.com/v1/status/{message_id}`  Returns the current delivery state of one message: pending, sent or failed, plus further lifecycle states as they occur. Covers paced text sends, voice memos and direct sends.
- `GET https://api.bluereacher.com/v1/conversations`  Chronological message history with per-message delivery channel (iMessage or SMS), tapback reactions and AI attribution. Cursor-paginated.
- `GET https://api.bluereacher.com/v1/groups`  Every group iMessage thread in the workspace: id, display name, participants, last activity and the owning line. Use a returned id to send into the thread or read its history.
- `GET https://api.bluereacher.com/v1/devices`  Every line in the workspace with online state, today's cold-outreach usage against its effective daily cap (warm-up aware), and queue depth. Use it to pick a line or check available capacity before a batch.
- `POST https://api.bluereacher.com/v1/reactions`  Queues one of the six classic tapbacks on a message; anything else is rejected rather than silently dropped.
- `DELETE https://api.bluereacher.com/v1/reactions`  Cancels a still-queued tapback before delivery, or genuinely removes an already-delivered one from the recipient's device.
- `POST https://api.bluereacher.com/v1/typing`  Lights the typing indicator on the recipient's device from your sending line, with a configurable window and a keepalive for longer holds.
- `POST https://api.bluereacher.com/v1/read`  Clears the connected CRM conversation's unread badge for a contact, and can queue a native mark-thread-read on the line itself.
- `GET https://api.bluereacher.com/v1/contacts`  Filter by exact phone, email, tag, created-after, or a free-text search across name and phone.
- `POST https://api.bluereacher.com/v1/contacts`  Creates the contact, or updates the existing one with the same phone number. The response says which happened.
- `PATCH https://api.bluereacher.com/v1/contacts/{contact_id}`  Partial update; custom fields merge with the existing map, and setting opted_out suppresses future platform sends to the contact.
- `GET https://api.bluereacher.com/v1/opt-out`  Exact E.164 match against the workspace's contacts, including whether the number is known at all.
- `POST https://api.bluereacher.com/v1/opt-out`  Opting out runs the same enforcement path as an inbound STOP reply: the contact is suppressed everywhere and the contact.opted_out webhook fires. Re-subscribing requires explicit confirmation and is deliberately harder than opting out.
- `GET https://api.bluereacher.com/v1/bot`  Returns the per-contact setting alongside an effective answer computed from the reply engine's own gate chain, distinguishing switched-on-and-replying from switched-on-but-nothing-will-answer.
- `POST https://api.bluereacher.com/v1/bot`  Mute the assistant for a contact, snooze it while a human takes over, return it to its own schedule, or set it to always reply.
- `POST https://api.bluereacher.com/v1/capability`  Batch lookup of up to 100 numbers. Known contacts answer instantly from observed delivery state; unknown numbers can queue a live probe.
- `POST https://api.bluereacher.com/v1/mcp`  Lists the calling lines available to the workspace with coarse readiness: ready, offline, busy, or not ready.
- `POST https://api.bluereacher.com/v1/mcp`  Prepares a FaceTime call and returns a short-lived confirmation URL. Never dials autonomously: a signed-in human opens the URL and presses to start the call.
- `POST https://api.bluereacher.com/v1/mcp`  Returns the lifecycle of a call prepared by this key, with stable states and failure codes.
- `POST https://api.bluereacher.com/v1/mcp`  Cancels a prepared call, or requests that its linked active call end. Safe to repeat.

Full request and response shapes: https://bluereacher.com/openapi.json

## Receiving inbound messages

Register a webhook to receive replies. Blue Reacher POSTs to your endpoint:

```
POST https://your-endpoint.example.com/inbound
{
  "from": "+15551234567",
  "content": "Sure, Thursday works",
  "channel": "imessage",
  "external_id": "your-contact-id"
}
```

## Rules an agent must follow

1. **Never send without the account owner's instruction.** These messages go to
   real people from a real number that belongs to a real business.
2. **Honor opt-outs immediately.** A STOP reply is handled automatically, but do
   not re-add a contact who has opted out.
3. **Check reachability before a first send** with `lookup_imessage` rather than
   assuming a number is on iMessage.
4. **Respect the line's daily capacity.** `list_devices` reports what is left.
   Exceeding it does not help; the messages queue.
5. **Do not fabricate consent.** The customer is responsible for having a
   lawful basis to contact each recipient.

## Other discovery surfaces

- https://bluereacher.com/llms.txt  page index
- https://bluereacher.com/llms-full.txt  expanded corpus
- https://bluereacher.com/openapi.json  API specification
- https://bluereacher.com/.well-known/mcp.json  MCP server card
- https://bluereacher.com/.well-known/agent-card.json  A2A agent card
- https://bluereacher.com/.well-known/api-catalog  RFC 9727 linkset
- https://docs.bluereacher.com  human documentation

## Contact

A human runs this. Reach them at https://bluereacher.com/book.