# API reference

> Every BloomText API endpoint, object, and webhook event, with parameters, example requests, and responses.

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

The BloomText API is a REST API with JSON request and response bodies, standard HTTP status codes, and bearer-token authentication. Everything on these pages is generated from the [OpenAPI 3.1 spec](https://www.bloomtext.com/developers/api/openapi/bloomtext-api.yaml), which you can also feed to any client generator.

```text filename="Base URL"
https://api.bloomtext.com/v1
```

> **Note:** New to the API? Start with the [Quickstart](https://www.bloomtext.com/developers/api/quickstart/), then read [Authentication](https://www.bloomtext.com/developers/api/authentication/) for keys and scopes.

## Resources

  - [Organization](https://www.bloomtext.com/developers/api/reference/organization-object/)
  - [Users](https://www.bloomtext.com/developers/api/reference/user-object/)
  - [Conversations](https://www.bloomtext.com/developers/api/reference/conversation-object/)
  - [Messages](https://www.bloomtext.com/developers/api/reference/message-object/)
  - [Reactions](https://www.bloomtext.com/developers/api/reference/reaction-object/)
  - [Participants](https://www.bloomtext.com/developers/api/reference/participant-object/)
  - [Broadcasts](https://www.bloomtext.com/developers/api/reference/broadcast-object/)
  - [Exports](https://www.bloomtext.com/developers/api/reference/export-object/)
  - [Webhook events](https://www.bloomtext.com/developers/api/reference/webhook-events/)

## Conventions

- **Authentication:** send `Authorization: Bearer bt_live_…` on every request. See [Authentication](https://www.bloomtext.com/developers/api/authentication/).
- **IDs:** every object has a stable UUID `id`.
- **Timestamps:** RFC 3339 strings in UTC, like `2026-09-21T12:00:00Z`.
- **Lists:** cursor-paginated with `page[limit]` and `page[after]`. 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/).

## All endpoints

### Organization

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/organization` | [Retrieve the organization](https://www.bloomtext.com/developers/api/reference/get-organization/) |

### Users

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/users` | [List users](https://www.bloomtext.com/developers/api/reference/list-users/) |
| GET | `/users/{userId}` | [Retrieve a user](https://www.bloomtext.com/developers/api/reference/get-user/) |

### Conversations

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/conversations` | [List conversations](https://www.bloomtext.com/developers/api/reference/list-conversations/) |
| GET | `/conversations/{conversationId}` | [Retrieve a conversation](https://www.bloomtext.com/developers/api/reference/get-conversation/) |

### Messages

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/conversations/{conversationId}/messages` | [List messages](https://www.bloomtext.com/developers/api/reference/list-messages/) |
| POST | `/conversations/{conversationId}/messages` | [Send a message](https://www.bloomtext.com/developers/api/reference/create-message/) |
| GET | `/messages/{messageId}/replies` | [List replies to a message](https://www.bloomtext.com/developers/api/reference/list-replies/) |

### Reactions

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/messages/{messageId}/reactions` | [List reactions](https://www.bloomtext.com/developers/api/reference/list-reactions/) |
| POST | `/messages/{messageId}/reactions` | [Add a reaction](https://www.bloomtext.com/developers/api/reference/create-reaction/) |
| DELETE | `/messages/{messageId}/reactions` | [Remove a reaction](https://www.bloomtext.com/developers/api/reference/delete-reaction/) |

### Participants

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/conversations/{conversationId}/participants` | [List conversation participants](https://www.bloomtext.com/developers/api/reference/list-participants/) |
| POST | `/conversations/{conversationId}/participants` | [Add a participant](https://www.bloomtext.com/developers/api/reference/add-participant/) |
| DELETE | `/conversations/{conversationId}/participants/{userId}` | [Remove a participant](https://www.bloomtext.com/developers/api/reference/remove-participant/) |

### Broadcasts

| Method | Path | Endpoint |
| --- | --- | --- |
| GET | `/broadcasts` | [List broadcasts](https://www.bloomtext.com/developers/api/reference/list-broadcasts/) |
| GET | `/broadcasts/{broadcastId}` | [Retrieve a broadcast](https://www.bloomtext.com/developers/api/reference/get-broadcast/) |
| GET | `/broadcasts/{broadcastId}/messages` | [List broadcast messages](https://www.bloomtext.com/developers/api/reference/list-broadcast-messages/) |

### Exports

| Method | Path | Endpoint |
| --- | --- | --- |
| POST | `/conversations/{conversationId}/exports` | [Export a conversation](https://www.bloomtext.com/developers/api/reference/create-chat-export/) |
| GET | `/exports/{exportId}` | [Retrieve an export](https://www.bloomtext.com/developers/api/reference/get-chat-export/) |