# Core concepts

> App users, conversations, and the other building blocks of the BloomText API.

Source: https://www.bloomtext.com/developers/api/concepts/

A few ideas explain almost everything about how the API behaves. Read this page once and the rest of the docs will make sense.

## Organizations

Everything in BloomText belongs to an organization: a practice, clinic, agency, or health system. An API key is issued to one organization and can never see data from another. [Retrieve the organization](https://www.bloomtext.com/developers/api/reference/get-organization/) to confirm which one a key belongs to.

## App users

Every API key belongs to an **app user**, a named member of your organization that represents your software, like "Intake Bot" or "Scheduling Sync".

- It shows up as the sender of every message it writes, so staff always know what came from an integration.
- It can't sign in to BloomText or administer the organization.
- It sees only the conversations it has been added to.

> **Note:** Create one app user per integration. If you run a reminder service and an AI assistant, give each its own app user and key so you can scope, audit, and revoke them separately.

## Conversations and membership

A [conversation](https://www.bloomtext.com/developers/api/reference/conversation-object/) is a thread between people in your organization and, often, a patient or family member. Conversations are `direct`, `group`, or `broadcast`.

**Membership is the access boundary.** Your app user can read and write a conversation only while it's a [participant](https://www.bloomtext.com/developers/api/reference/participant-object/). Scopes decide *what* a key can do; membership decides *where*.

```mermaid
flowchart LR
  Key[API key] -->|belongs to| AppUser[App user]
  AppUser -->|participant in| C1[Conversation A]
  AppUser -->|participant in| C2[Conversation B]
  AppUser -.->|not a participant| C3[Conversation C]
  style C3 stroke-dasharray: 4 4
```

## Messages, replies, and reactions

- A [message](https://www.bloomtext.com/developers/api/reference/message-object/) carries either text (`body`) or a file (`file`).
- A reply is a message with `reply_to_message_id` set. [List replies](https://www.bloomtext.com/developers/api/reference/list-replies/) returns a message's thread.
- [Reactions](https://www.bloomtext.com/developers/api/reference/reaction-object/) are emoji on a message. They have no ID of their own; each is identified by the message, the user, and the emoji.

## Broadcasts

A [broadcast](https://www.bloomtext.com/developers/api/reference/broadcast-object/) is a one-to-many campaign your staff send from BloomText. The API lets you read broadcasts and their delivery status. Reading a broadcast never grants access to the conversations it was sent to.

## Exports

An [export](https://www.bloomtext.com/developers/api/reference/export-object/) packages a conversation's history into a file. Exports run asynchronously: start one, then poll it or listen for the `export.ready` [webhook](https://www.bloomtext.com/developers/api/webhooks/) to get a short-lived download URL.

## IDs, timestamps, and requests

| Convention | Detail |
| --- | --- |
| Base URL | `https://api.bloomtext.com/v1` |
| IDs | Every object has a stable UUID `id`. |
| Timestamps | RFC 3339 strings in UTC, like `2026-09-21T12:00:00Z`. |
| Bodies | JSON in and out. Send `Content-Type: application/json`. |
| Lists | Cursor-paginated. See [Pagination](https://www.bloomtext.com/developers/api/pagination/). |
| Writes | Every `POST` takes an `Idempotency-Key`. See [Idempotency](https://www.bloomtext.com/developers/api/idempotency/). |
| Errors | RFC 9457 problem details. See [Errors](https://www.bloomtext.com/developers/api/errors/). |