Communication API Reference

All Communication endpoints are served under the /api/v1/communication prefix via the gateway.

Endpoints

Channels

Method	Path	Description
GET	/api/v1/communication/channels	List channels (filter: ?status=active|disabled)
POST	/api/v1/communication/channels	Create channel
GET	/api/v1/communication/channels/:id	Get channel by ID or name
PATCH	/api/v1/communication/channels/:id	Update channel
DELETE	/api/v1/communication/channels/:id	Delete channel

Registrations

Method	Path	Description
GET	/api/v1/communication/apps/:appId/channels	List app registrations (filter: ?channelId=)
POST	/api/v1/communication/apps/:appId/channels	Register app against channel
GET	/api/v1/communication/apps/:appId/channels/:id	Get registration
PATCH	/api/v1/communication/apps/:appId/channels/:id	Update registration
DELETE	/api/v1/communication/apps/:appId/channels/:id	Delete registration

Sending & Deliveries

Method	Path	Description
POST	/api/v1/communication/apps/:appId/send	Send message
GET	/api/v1/communication/apps/:appId/deliveries	List deliveries (filter: ?channelId=, ?limit=)

Examples

Create a Channel

curl -X POST http://localhost:3000/api/v1/communication/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "slack-alerts",
    "provider": "slack",
    "description": "Team alert notifications",
    "config": {
      "webhookUrl": "env:SLACK_WEBHOOK_URL"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "ch_abc123def456",
    "name": "slack-alerts",
    "provider": "slack",
    "description": "Team alert notifications",
    "status": "active",
    "config": { "webhookUrl": "env:SLACK_WEBHOOK_URL" },
    "createdAt": "2026-03-05T12:00:00.000Z",
    "updatedAt": "2026-03-05T12:00:00.000Z"
  }
}

Register an App

curl -X POST http://localhost:3000/api/v1/communication/apps/my-service/channels \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ch_abc123def456",
    "target": "#deploy-alerts",
    "metadata": { "env": "production" }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "reg_xyz789ghi012",
    "appId": "my-service",
    "channelId": "ch_abc123def456",
    "target": "#deploy-alerts",
    "metadata": { "env": "production" },
    "enabled": true,
    "createdAt": "2026-03-05T12:00:00.000Z",
    "updatedAt": "2026-03-05T12:00:00.000Z"
  }
}

Send a Message

curl -X POST http://localhost:3000/api/v1/communication/apps/my-service/send \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ch_abc123def456",
    "text": "Deployment to production complete",
    "subject": "Deploy notification"
  }'

Response:

{
  "success": true,
  "data": {
    "delivery": {
      "id": "dl_qrs345tuv678",
      "appId": "my-service",
      "channelId": "ch_abc123def456",
      "provider": "slack",
      "target": "#deploy-alerts",
      "status": "accepted",
      "providerMessageId": "slack-msg-123",
      "live": true,
      "createdAt": "2026-03-05T12:00:00.000Z"
    },
    "provider": "slack",
    "live": true
  }
}

List Deliveries

curl "http://localhost:3000/api/v1/communication/apps/my-service/deliveries?limit=10"

Update a Channel

curl -X PATCH http://localhost:3000/api/v1/communication/channels/ch_abc123def456 \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'

List Channels

curl "http://localhost:3000/api/v1/communication/channels?status=active"

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Channel not found: ch_abc123def456"
  }
}