Send your first message

By the end of this page you have a token, a story.context snapshot accepted with 202, and your story on the portal's story timeline.

You need:

	Example
A connected producer app's client id and secret	From Apps and credentials. See Credentials
Your workspace id, {t}	w…, shown with the credentials, and the tenant claim of your token
The Bus API	https://api.sombus.rnd-solutions.net/v1/ (the Sandbox)
A system_id your app may stamp	acme-ncs-test

1. Get a token

TOKEN=$(curl -s https://api.sombus.rnd-solutions.net/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials | jq -r .access_token)

Reuse it for its hour. An app signing with an AWS role or your own identity provider skips this step: see Authenticate.

2. Build the message

Take snapshot 1 of the published hurricane run as the payload, give it your own story_id, and wrap it in an envelope:

{
  "som_version": "1.0.0",
  "message_id": "<a new UUIDv7>",
  "correlation_id": "<a new UUID for this story>",
  "message_type": "story.context",
  "timestamp": "<now, RFC 3339 with a time zone>",
  "originating_system": { "system_id": "acme-ncs-test", "system_type": "ncs", "vendor": "acme", "version": "4.2.0" },
  "topic": "som.story.context",
  "payload": { "story_id": "acme-ncs-hurricane-run-1", "sequence_number": 1, "…": "the rest of hurricane-01.json" }
}

Keep the correlation_id: every later message about this story uses it. What each field must hold is on The envelope.

As a script:

SOM=https://raw.githubusercontent.com/storyobjectmodel/som/7297fef9adc6d14a74bdd7550c78decaa099a1ad/examples/hurricane-run
curl -sO $SOM/hurricane-01.json

STORY=acme-ncs-$(date +%s)                # a new story_id per run
CORR=$(uuidgen | tr A-Z a-z)              # one correlation_id for the whole story
jq --arg mid "$(uuidgen | tr A-Z a-z)" --arg cid "$CORR" --arg story "$STORY" \
   --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '{som_version: "1.0.0", message_id: $mid, correlation_id: $cid, message_type: "story.context",
    timestamp: $ts, originating_system: {system_id: "acme-ncs-test", system_type: "ncs"},
    topic: "som.story.context", payload: (. + {story_id: $story})}' hurricane-01.json > first.json

uuidgen makes a version 4 UUID, which is valid. In your product, prefer UUIDv7: it sorts by time.

3. Dry-run it

curl -s https://api.sombus.rnd-solutions.net/v1/tenants/$WORKSPACE/validate \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data-binary @first.json

{"accepted":true,"dry_run":true,"message_id":"…","message_type":"story.context","family":"story-context"}

The same checks as a publish, with your app's own grants and your workspace's story state. Nothing is published or recorded, so you can run it as often as you need, from your CI too, within your connection's limits: each dry run counts as a request (Limits).

4. Publish

curl -s https://api.sombus.rnd-solutions.net/v1/tenants/$WORKSPACE/messages \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data-binary @first.json

{"accepted":true,"message_id":"…","message_type":"story.context","family":"story-context"}

That's a 202: validated, recorded, and accepted and published for delivery to every consumer connection in your workspace that subscribes to story.context. Their queues receive it moments later.

Now send exactly the same file again. You get 200 with "duplicate":true: the bus recognised a retry, and nothing was delivered twice. See Retries and idempotency.

If you got something else

You got	Most likely	Fix
401 producer.unauthenticated	Token missing, expired or malformed, from the other environment, or issued before a rotation	Get a fresh token from your environment's token service; check the Bearer prefix
403 producer.not_registered	Valid token, but the connection was revoked	Check the connection on Apps and credentials; connect the app again if needed
403 tenant.mismatch	{t} isn't the workspace your credentials belong to	Use the tenant claim of your token
403 producer.system_id_not_allowed	originating_system.system_id isn't one of your connection's	Use one of its system_ids, or connect the app again with it
400 with source: schema	The message isn't valid SOM 1.0	Read rule and path; paste the message into the Playground
409 sequence_number.not_increasing	That story_id already exists in your workspace	Use a new story_id for every run

Every answer, and what to do with it: Handle the bus's answers.

5. See it in the portal

• Story timeline lists your story with its headline, story_type and last sequence_number. Open it to see each message in order, and what changed between snapshots.
• Activity shows the gateway's latest decisions, the last 24 hours by default and up to 7 days, at most 200 at a time, with the rule ids behind each refusal. Never payloads.

Only your workspace's traffic shows. An app RND registered in the bus configuration isn't in a workspace, so ask RND for its activity (see Authenticate).

Checkpoint

• [ ] My product gets a token and reuses it until shortly before it expires.
• [ ] My first snapshot passed the dry run, then got 202, and an identical resend got 200 with duplicate.
• [ ] I can find my story on the portal's story timeline.

Next: Run a whole story.