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 when the BRIDGE_SECRET environment variable is configured. When BRIDGE_SECRET is not set, authentication is disabled (development mode only).

Header	Type	Required	Description
x-bridge-secret	string	Yes (when BRIDGE_SECRET is set)	Shared secret for authenticating bridge requests. Must match the server-side BRIDGE_SECRET value.

Unauthenticated requests return a 401 response:

{
  "error": "unauthorized"
}

In production, always set the BRIDGE_SECRET environment variable to secure the bridge endpoints. Without it, any caller can send and read bridge messages.

Send a message

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

{
  "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	unauthorized — 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

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

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

{
  "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	unauthorized — missing or invalid x-bridge-secret header
500	Failed to fetch messages

Example

curl -H "x-bridge-secret: your-bridge-secret" \
  "/api/bridge/inbox?channel=tasks&reader=atlas-main&limit=10"

Bridge health

GET /api/bridge/health

Returns the current status of the bridge message bus, including total message count, last message metadata, and available channels.

Response

{
  "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

{
  "status": "error",
  "error": "database unreachable"
}

Code	Description
200	Bridge health check succeeded
401	unauthorized — missing or invalid x-bridge-secret header
500	Database is unreachable