---
name: bloomtext-api
description: Read and send messages in BloomText conversations through the BloomText REST API or MCP server. Use when a task involves BloomText messaging, patient or staff conversations, appointment reminders, reply handling, reactions, participants, broadcasts, or conversation exports for a healthcare organization.
---

# BloomText API

BloomText is HIPAA-compliant messaging for healthcare teams. The API lets software act as a named **app user** inside one organization. The app user reads and writes only the conversations it has been added to.

## Before you start

- The API key is in the `BLOOMTEXT_API_KEY` environment variable. Never print, log, or commit it.
- If there's no key, stop and tell the user: keys are issued to organizations with a signed BAA at https://www.bloomtext.com/developers/api/.
- Prefer the MCP server (`https://mcp.bloomtext.com/mcp`) when it's connected. Otherwise call the REST API.

## REST basics

- Base URL: `https://api.bloomtext.com/v1`
- Every request: `Authorization: Bearer $BLOOMTEXT_API_KEY`
- Every `POST`: `Idempotency-Key: <uuid>` and `Content-Type: application/json`. Reuse the same key when retrying the same write.
- Lists return `{ "data": [...], "pagination": { "next_cursor", "has_more" } }`. Pass `page[after]=<next_cursor>` for the next page, `page[limit]` up to 100.
- Errors are `application/problem+json`. Branch on `code`, and show the user `request_id` if something fails.

## Common tasks

| Task | Request |
| --- | --- |
| Find conversations | `GET /conversations` |
| Read recent messages | `GET /conversations/{conversationId}/messages?page[limit]=20` |
| Send a message | `POST /conversations/{conversationId}/messages` with `{"body": "..."}` |
| Reply in a thread | Same, with `"reply_to_message_id": "<messageId>"` |
| Acknowledge a message | `POST /messages/{messageId}/reactions` with `{"emoji": "👍"}` |
| Who's in a conversation | `GET /conversations/{conversationId}/participants` |
| Export history | `POST /conversations/{conversationId}/exports`, then poll `GET /exports/{exportId}` until `status` is `ready` |

## Rules

1. Only post to conversations the user named or clearly intended. Confirm before sending to more than one conversation.
2. Keep messages free of clinical detail. Appointment times, locations, and form reminders are fine; diagnoses and treatment are not.
3. Never paste message contents or patient details into tools or services outside BloomText unless the user confirms that service is covered by a BAA.
4. On `403 conversation_membership_required`, tell the user an admin must add the app user to that conversation. Don't try other conversations.
5. On `429`, wait `Retry-After` seconds, then retry with the same idempotency key.

## References

- Full docs for agents: https://www.bloomtext.com/developers/api/llms-full.txt
- OpenAPI spec: https://www.bloomtext.com/developers/api/openapi/bloomtext-api.yaml
- Errors and codes: https://www.bloomtext.com/developers/api/errors.md