### GET /health

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Provides a basic liveness probe for the gateway server.

```APIDOC
## GET /health

### Description
A basic liveness probe for the gateway server.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200 OK)
- **status** (string) - `ok`

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### GET /api/messages/out/:networkId/:botId

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Subscribe to receive outbound messages for a specific network and bot. This is where adaptors fetch messages to deliver.

```APIDOC
## GET /api/messages/out/:networkId/:botId

### Description
Subscribe to receive outbound messages for a specific network and bot. This is where adaptors fetch messages to deliver.

### Method
GET

### Endpoint
/api/messages/out/:networkId/:botId

### Parameters
#### Path Parameters
- **networkId** (string) - Required - The ID of the network.
- **botId** (string) - Required - The ID of the bot.

### Response
#### Success Response (200)
- **messages** (array) - An array of outbound messages.
  - **message** (string) - The content of the message.
  - **timestamp** (string) - The timestamp of the message.

#### Response Example
```json
{
  "messages": [
    {
      "message": "This is an outbound message.",
      "timestamp": "2023-01-01T12:00:00Z"
    }
  ]
}
```

#### Error Response (404)
- **error** (string) - Description of the error.

#### Error Example
```json
{
  "error": "No messages found for the specified network and bot."
}
```
```

--------------------------------

### GET /api/messages/in/:networkId/:botId

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Subscribe to receive inbound messages for observability. This endpoint provides a stream of messages for monitoring purposes.

```APIDOC
## GET /api/messages/in/:networkId/:botId

### Description
Subscribe to receive inbound messages for observability. This endpoint provides a stream of messages for monitoring purposes.

### Method
GET

### Endpoint
/api/messages/in/:networkId/:botId

### Parameters
#### Path Parameters
- **networkId** (string) - Required - The ID of the network.
- **botId** (string) - Required - The ID of the bot.

### Response
#### Success Response (200)
- **messages** (array) - An array of inbound messages.
  - **message** (string) - The content of the message.
  - **timestamp** (string) - The timestamp of the message.

#### Response Example
```json
{
  "messages": [
    {
      "message": "This is an inbound message for monitoring.",
      "timestamp": "2023-01-01T12:05:00Z"
    }
  ]
}
```

#### Error Response (404)
- **error** (string) - Description of the error.

#### Error Example
```json
{
  "error": "No inbound messages found for the specified network and bot."
}
```
```

--------------------------------

### POST /api/messages

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Submits an inbound message to the gateway, forwarding it to the appropriate CVM and publishing it to the 'in' SSE stream.

```APIDOC
## POST /api/messages

### Description
Accepts an inbound message from an adaptor and forwards it to the appropriate CVM (Brain or ID). Also publishes the inbound message to the `in` SSE stream for observability.

### Method
POST

### Endpoint
/api/messages

### Parameters
#### Request Body
- **networkId** (string) - Required - e.g. `signal`, `whatsapp`
- **botId** (string) - Required - adaptor‑specific bot or device identifier
- **botType** (string) - Required - `brain` | `id` (selects target CVM)
- **groupId** (string) - Optional
- **userId** (string) - Optional
- **messageId** (string) - Optional - original incoming message id (used to correlate replies)
- **message** (string) - Required - message content

### Request Example
```json
{
  "networkId": "signal",
  "botId": "123",
  "botType": "brain",
  "messageId": "abc",
  "message": "hi there"
}
```

### Response
#### Success Response (202 Accepted)
- **status** (string) - `in_progress` when fire‑and‑forget forwarding is enabled.

#### Success Response (200 OK)
- **status** (string) - `accepted`
- **cvm** (object) - CVM response details

#### Response Example (202 Accepted)
```json
{
  "status": "in_progress"
}
```

#### Response Example (200 OK)
```json
{
  "status": "accepted",
  "cvm": {}
}
```

#### Error Response (400 Bad Request)
- **error** (string) - e.g. `missing_field:<name>`, `invalid_field:botType`, `invalid_json`

#### Error Response (502 Bad Gateway / 504 Gateway Timeout)
- **status** (string) - `rejected` or `error`
```

--------------------------------

### SSE Streams (Inbound and Outbound)

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Provides Server-Sent Events (SSE) streams for inbound messages received by the gateway and outbound messages to be sent by adaptors.

```APIDOC
## SSE Streams (Inbound and Outbound)

### Description
Provides Server-Sent Events (SSE) streams for inbound messages received by the gateway and outbound messages to be sent by adaptors. Supports reconnection and backfill.

### Method
GET

### Endpoint
- Inbound (received by gateway): `/api/messages/:networkId/:botId` (back-compat)
- Inbound (received by gateway): `/api/messages/in/:networkId/:botId`
- Outbound (to be sent by adaptors): `/api/messages/out/:networkId/:botId`

### Parameters
#### Path Parameters
- **networkId** (string) - Required - The messaging network identifier.
- **botId** (string) - Required - The adaptor-specific bot or device identifier.

### Event Stream Format
- **Content-Type**: `text/event-stream`
- **Heartbeats**: Comment lines `: ping` at `HEARTBEAT_MS` (default 15000ms).
- **Message Event**: 
  - `id`: `<monotonic-per-channel>`
  - `event`: `message`
  - `data`: JSON object with message details:
    - `networkId` (string)
    - `botId` (string)
    - `botType` (`brain` | `id`)
    - `groupId?` (string)
    - `userId?` (string)
    - `replyMessageId?` (string) - Set to the original `POST.messageId` when present.
    - `message` (string)
    - `direction` (`in` | `out`)

### Reconnection and Backfill
- Clients can send `Last-Event-ID` (or `last-event-id`) header to receive missed events.
- Each stream maintains a ring buffer (capacity `MAX_MESSAGES_PER_CHANNEL`, default 500).

### CORS
- `access-control-allow-origin: *` is set for both POST and SSE endpoints.

### Usage Pattern for Adaptors
- Listen on `/api/messages/out/:networkId/:botId` to receive messages for delivery.
- POST delivery receipts or new inbound user messages to `/api/messages`.
```

--------------------------------

### Subscribe to Outbound SSE Stream (curl)

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

This command enables an adaptor to subscribe to the Server-Sent Events (SSE) stream for outbound messages. Adaptors listen to this stream to receive messages that need to be delivered to the respective messaging networks.

```shell
curl -N http://localhost:3030/api/messages/out/signal/123
```

--------------------------------

### Subscribe to Inbound SSE Stream (curl)

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

This command allows an adaptor to subscribe to the Server-Sent Events (SSE) stream for inbound messages received by the gateway. This is useful for monitoring messages as they arrive before being processed by the CVM.

```shell
curl -N http://localhost:3030/api/messages/in/signal/123
```

--------------------------------

### Submit Inbound Message to Gateway (curl)

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

This command demonstrates how to send an inbound message to the beacon-gateway. It specifies the network, bot, message details, and content. The server forwards this to a CVM and may return a status indicating processing or acceptance.

```shell
curl -X POST http://localhost:3030/api/messages \
  -H 'content-type: application/json' \
  -d '{
        "networkId":"signal",
        "botId":"123",
        "botType":"brain",
        "messageId":"abc",
        "message":"hi there"
      }'
```

--------------------------------

### Health Check Endpoint (curl)

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

This command performs a basic liveness probe against the beacon-gateway's health endpoint. It is used to quickly check if the server is running and responsive.

```shell
curl http://localhost:3030/health
```

--------------------------------

### POST /api/messages

Source: https://github.com/beacon21m/beacon-gateway/blob/main/README.md

Send a message through the gateway. This endpoint is used by adaptors to forward messages to the appropriate CVM server.

```APIDOC
## POST /api/messages

### Description
Send a message through the gateway. This endpoint is used by adaptors to forward messages to the appropriate CVM server.

### Method
POST

### Endpoint
/api/messages

### Parameters
#### Request Body
- **networkId** (string) - Required - The ID of the network the message is for.
- **botId** (string) - Required - The ID of the bot sending the message.
- **botType** (string) - Required - The type of bot ('brain' or 'id').
- **message** (string) - Required - The content of the message.

### Request Example
```json
{
  "networkId": "some_network_id",
  "botId": "some_bot_id",
  "botType": "brain",
  "message": "Hello from the adaptor!"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the message submission.

#### Response Example
```json
{
  "status": "sent"
}
```

#### Error Response (400)
- **error** (string) - Description of the error.

#### Error Example
```json
{
  "error": "Invalid input parameters"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.