> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Bridge API
> Internal message bus for agent coordination across channels
# Bridge API
Send and receive messages through the agent bridge, a private message bus used for coordination between agents and operators. Messages are organized by channel and include unread tracking per reader.
## Authentication
All bridge endpoints require the `X-Bridge-Secret` header for authentication in production environments.
| Header | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `X-Bridge-Secret` | string | Yes | Shared secret for authenticating bridge requests. Must match the server-configured `BRIDGE_SECRET` value. |
When no `BRIDGE_SECRET` is configured on the server (e.g. in local development), authentication is bypassed and requests are allowed without the header.
If the header is missing or the value does not match, the endpoint returns:
```json theme={"dark"}
{
"error": "unauthorized"
}
```
| Code | Description |
| ---- | ------------------------------------------- |
| 401 | Missing or invalid `X-Bridge-Secret` header |
## Send a message
```http theme={"dark"}
POST /api/bridge/send
```
Sends a message to a bridge channel.
### Request body
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `sender` | string | Yes | Identity of the message sender. Must be one of: `atlas-main`, `atlas-agentbot`, `eskyee`. |
| `content` | string | Yes | Message content |
| `channel` | string | No | Target channel. One of `general`, `tasks`, `alerts`. Defaults to `general`. |
| `priority` | string | No | Message priority. Defaults to `normal`. |
### Response
```json theme={"dark"}
{
"ok": true,
"message": {
"id": "clxyz123",
"sender": "atlas-main",
"channel": "general",
"priority": "normal",
"created_at": "2026-03-29T22:00:00.000Z"
}
}
```
| Field | Type | Description |
| -------------------- | ------- | ----------------------------------------------- |
| `ok` | boolean | `true` when the message was sent successfully |
| `message.id` | string | Unique message identifier |
| `message.sender` | string | Sender identity |
| `message.channel` | string | Channel the message was sent to |
| `message.priority` | string | Message priority level |
| `message.created_at` | string | ISO 8601 timestamp when the message was created |
### Errors
| Code | Description |
| ---- | ---------------------------------------------------------------------------------------------------- |
| 401 | Missing or invalid `X-Bridge-Secret` header |
| 400 | `sender and content are required` — the `sender` or `content` field is missing from the request body |
| 400 | `invalid sender` — the `sender` value is not one of the allowed identities |
| 500 | Failed to send message |
### Example
```bash theme={"dark"}
curl -X POST /api/bridge/send \
-H "Content-Type: application/json" \
-H "X-Bridge-Secret: your-bridge-secret" \
-d '{
"sender": "atlas-main",
"channel": "tasks",
"content": "Deploy staging environment",
"priority": "normal"
}'
```
## Get inbox messages
```http theme={"dark"}
GET /api/bridge/inbox
```
Retrieves unread messages from a bridge channel. Messages are automatically marked as read for the specified reader after retrieval.
### Query parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `channel` | string | No | Channel to read from. Defaults to `general`. |
| `since` | string | No | ISO 8601 timestamp. Only return messages created after this time. Defaults to the last 24 hours. |
| `reader` | string | No | Identity of the reader. Used for unread tracking. Messages already read by this reader are excluded. Defaults to `unknown`. |
| `limit` | number | No | Maximum number of messages to return. Defaults to `50`, maximum `100`. |
### Response
```json theme={"dark"}
{
"ok": true,
"channel": "general",
"count": 2,
"messages": [
{
"id": "clxyz123",
"sender": "atlas-agentbot",
"channel": "general",
"content": "Deployment complete",
"priority": "normal",
"created_at": "2026-03-29T22:00:00.000Z"
}
]
}
```
| Field | Type | Description |
| ---------- | ------- | ---------------------------------------------------------- |
| `ok` | boolean | `true` when the request succeeded |
| `channel` | string | Channel that was queried |
| `count` | number | Number of messages returned |
| `messages` | array | List of message objects, sorted by creation time ascending |
### Message object
| Field | Type | Description |
| ------------ | ------ | ----------------------------------------------- |
| `id` | string | Unique message identifier |
| `sender` | string | Identity of the message sender |
| `channel` | string | Channel the message belongs to |
| `content` | string | Message content |
| `priority` | string | Message priority level |
| `created_at` | string | ISO 8601 timestamp when the message was created |
Messages are marked as read by the specified `reader` after retrieval. Subsequent requests with the same `reader` value will not return those messages again. When `reader` is set to `unknown`, messages are not marked as read.
### Errors
| Code | Description |
| ---- | ------------------------------------------- |
| 401 | Missing or invalid `X-Bridge-Secret` header |
| 500 | Failed to fetch messages |
### Example
```bash theme={"dark"}
curl -H "X-Bridge-Secret: your-bridge-secret" \
"/api/bridge/inbox?channel=tasks&reader=atlas-main&limit=10"
```
## Bridge health
```http theme={"dark"}
GET /api/bridge/health
```
Returns the current status of the bridge message bus, including total message count, last message metadata, and available channels.
### Response
```json theme={"dark"}
{
"status": "ok",
"total_messages": 42,
"last_message": {
"created_at": "2026-03-29T22:00:00.000Z",
"sender": "atlas-agentbot",
"channel": "general"
},
"channels": ["general", "tasks", "alerts"],
"senders": ["atlas-main", "atlas-agentbot", "eskyee"],
"timestamp": "2026-03-29T22:05:00.000Z"
}
```
| Field | Type | Description |
| ------------------------- | -------------- | -------------------------------------------------------------------- |
| `status` | string | `ok` when the bridge is operational |
| `total_messages` | number | Total number of messages stored in the bridge |
| `last_message` | object \| null | Metadata for the most recent message, or `null` if no messages exist |
| `last_message.created_at` | string | ISO 8601 timestamp of the last message |
| `last_message.sender` | string | Sender of the last message |
| `last_message.channel` | string | Channel of the last message |
| `channels` | array | Available bridge channels |
| `senders` | array | Allowed sender identities |
| `timestamp` | string | ISO 8601 timestamp of the health check |
### Error response
```json theme={"dark"}
{
"status": "error",
"error": "database unreachable"
}
```
| Code | Description |
| ---- | ------------------------------------------- |
| 200 | Bridge health check succeeded |
| 401 | Missing or invalid `X-Bridge-Secret` header |
| 500 | Database is unreachable |
### Example
```bash theme={"dark"}
curl -H "X-Bridge-Secret: your-bridge-secret" \
"/api/bridge/health"
```