Bus API

Base URLs

Environment	Base URL
Sandbox	https://api.sombus.rnd-solutions.net/v1/
Preview	https://api.staging.sombus.rnd-solutions.net/v1/

HTTPS only. See Environments.

Endpoints

{t} is your workspace id and {c} a consumer connection's id.

Method and path	Auth	Status	Purpose
GET /v1/health	None	Available now	Liveness, SOM version and the message types the bus has schemas for
POST /v1/oauth/token	Client id and secret	Available now	Get an access token from the bus's token service. See Token service and workspace API
GET /v1/oauth/jwks	None	Available now	The token service's public signing key
POST /v1/tenants/{t}/messages	Bus access token, or your identity provider's token	Available now	Publish one SOM message to your workspace
POST /v1/tenants/{t}/validate	Bus access token, or your identity provider's token	Available now	Dry run: check a message with your connection's grants and your workspace's story state, without publishing
POST /v1/tenants/{t}/iam/messages, /iam/validate	AWS SigV4 (IAM)	Available now	Publish or dry-run, signed by the AWS role registered and verified on the connection. See Authenticate
POST /v1/tenants/{t}/principals/verify	AWS SigV4 (IAM)	Available now	Prove the registered AWS role is yours, with the one-time challenge from the portal
GET /v1/tenants/{t}/consumers/{c}/messages	Bus access token (consumer)	Available now	Receive up to 10 messages, long-polling up to 20 seconds. See HTTPS pull API
POST /v1/tenants/{t}/consumers/{c}/ack	Bus access token (consumer)	Available now	Acknowledge received messages by receipt handle
POST /v1/tenants/{t}/consumers/{c}/nack	Bus access token (consumer)	Available now	Release received messages for redelivery
GET /v1/tenants/{t}/consumers/{c}/skills	Bus access token (consumer)	Available now	A skill executor's registrations: the configured instances the house bound to this connection. See Registrations
POST /v1/jwt/messages	A token from the token URL RND sent you	Via RND	Publish, for an app RND manages in the bus configuration. See Authenticate
POST /v1/messages	AWS SigV4 (IAM)	Via RND	Publish, for an app RND manages in the bus configuration, signed with a role RND registered

A token from your own identity provider works on the messages and validate routes once its client is bound to a connection: see Authenticate.

The portal's own /api/* routes serve the portal. They're not a supported integration API.

GET /v1/health

GET /v1/health

{ "ok": true, "som_version": "1.0.0",
  "message_types": ["delivery.media_available", "link.committed", "link.gate_changed", "link.withdrawn",
                    "skill.warning.raised", "story.context", "system.audit",
                    "telling.ended", "telling.exposed", "telling.started"] }

Getting a token

POST /v1/oauth/token
Authorization: Basic base64(<client_id>:<client_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }

• Lifetime: 1 hour. Cache and reuse it; refresh shortly before expiry.
• The token identifies your connection: your app in one workspace. The bus looks up its grants on every request.
• Details, claims and errors: Token service and workspace API. Other ways to sign in: Authenticate.

Publishing

POST /v1/tenants/{t}/messages
Authorization: Bearer <access_token>
Content-Type: application/json

{ …one SOM 1.0 message: envelope and payload… }

• One message per request. No batching.
• Body: at most 240,000 bytes, UTF-8 JSON.
• The bus never changes your message: readers of a queue with AWS credentials get your exact bytes, and the pull API returns the same envelope, parsed.
• Every publish route takes the same body and returns the same responses, whatever the authentication. /validate answers as a publish would, with "dry_run": true, and publishes nothing.

Responses

All responses are JSON:

// 202 Accepted: validated, committed and published to consumers
{ accepted: true, message_id: string, message_type: string, family: string | null, tolerated?: Violation[],
  dry_run?: true }   // dry_run: on the validate routes, where nothing is published

// 200 OK: duplicate of an accepted message (same message_id, same content)
{ accepted: true, duplicate: true, message_id: string }

// 400 / 401 / 403 / 409 / 413 / 429 / 503: refused
{ accepted: false, violations: Violation[] }

interface Violation {
  source: 'schema' | 'conformance' | 'sequence' | 'policy';
  rule: string;       // stable id: see the rule catalogue
  message: string;    // for people; may change, don't parse it
  path?: string;      // JSON Pointer into your message, where known
}

What each status means: Verdicts and refusals. What each rule means: the rule catalogue.

Guarantees

Validation	Every message on the bus passed the gateway. Consumers never see a refused message
Order	Per correlation_id, in the order the bus published them. None across different correlation_ids
Delivery	At least once. Consumers must be idempotent on message_id
Idempotency window	At least 7 days per message_id
Content	The message is never changed. Readers of the queue with AWS credentials receive the producer's exact bytes; the HTTPS pull API returns the same envelope, parsed, as JSON
Consumer queue retention	14 days
Replay archive	30 days (Sandbox), 7 days (Preview); replay per consumer connection, from the portal
Rate limit	200 requests a second, bursts of 400, for the whole API; 600 requests a minute per source address; per connection on the workspace routes, except the signed /iam/… routes, whose limit all AWS signers share. See Limits. Over a limit: 429 rate.limited
Throughput	Functional testing only. Ask RND before sending more than a few messages a second