Protocol sandbox
Bifrost: the bridge between worlds, on the same engine.
Your tasks
A code appears when a task is done – type it into the lesson.
Tasks check what you did, so they need your account.
Your token goes with the connection as ?token=.Signed out: the server closes the connection with 4401. Sign in
- Connect, then send the subscribe frame. Events of your raven appear here as they happen.
Ravens – WebSocket
C6.11Subscribe to one of your ravens (RVN-1 to RVN-3) and receive its flight as it happens.
| Direction | Frame | Meaning |
|---|---|---|
| you send | {"type":"subscribe","raven_id":…} | Follow one raven. The value is RVN-1, RVN-2 or RVN-3. |
| you send | {"type":"unsubscribe",…} | Stop following it. |
| you send | {"type":"ping"} | Application-level ping. |
| you get | {"type":"subscribed",…} | Your subscription is on. Events of that raven follow. |
| you get | {"type":"raven.status","seq":…,"status":…} | One status change: released, lost_in_frost, on_the_bridge, at_the_far_gate, delivered, recalled. |
| you get | {"type":"pong"} | The answer to your ping. |
| you get | {"type":"error","code":…} | Something is wrong with your frame. The connection stays open. |
Every frame is JSON text. Events of one raven arrive in order with a growing seq. Packing and shipping are simulated: a few seconds after payment. A frame you cannot use gets an error frame, not a closed connection.
How to call it from your tools
In Postman
1Create the request: New → WebSocket, then enter the URL
2Before you connect, open Headers and add Authorization with the value Bearer and your token. Or add a token parameter in Params.
3Press Connect. Without a token the connection opens and closes at once with code 4401.
4In the message composer choose JSON, paste this and press Send. The value is RVN-1, RVN-2 or RVN-3.
5Watch the messages list. Send a wrong value to see an error frame; send a ping to get a pong.
With wscat
Then type the subscribe frame and press Enter. An event looks like this:
And a mistake like this (the connection stays open):
Close codes
| Close code | When |
|---|---|
4401 | No token or API key, or an invalid one. |
4429 | More than 5 open connections for your account. |
1009 | A frame larger than 4 KB. |
1001 | The server is stopping. |
Echo stone – WebSocket
Whatever you send comes back unchanged. No token needed – the place to try your first connection.
| You send | You get |
|---|---|
| any text frame | the same text |
| any binary frame | the same bytes, as binary |
ping | pong (a word, not a control frame) |
| a frame over 4 KB | close code 1009 |
How to call it from your tools
Address (no token needed; add ?token= to count it for your task)
wscat
Halls – WebSocket chat
Enter a hall with your token and talk; Huginn answers some words. Your halls are yours alone: a message reaches only your own connections.
| Direction | Frame | Meaning |
|---|---|---|
| you send | {"type":"message","text":"…"} | 1–500 characters. Reaches your own connections in the room; Huginn answers some words. |
| you send | {"type":"bye"} | The server closes with 1001. |
| you send | {"type":"freeze"} | The server drops the connection without a close frame (your client reports 1006). |
| you get | {"type":"system","text":…,"room":…,"users":…} | You entered the room. |
| you get | {"type":"message","user":…,"text":…,"ts":…} | A message in the room. |
| you get | {"type":"error","code":…} | room_not_found, bad_message, unknown_type – the connection stays open. |
Rooms: valhalla, asgard, midgard (default valhalla). Without a token the server closes with 4401.
How to call it from your tools
Address
A message
Watch-post – WebSocket feed
The watch-post calls out one line after another from a fixed list: choose how many and how often, pause and resume.
| Query parameter | Values |
|---|---|
interval_ms | 200–5000, default 1000 |
count | 1–100; without it the feed does not end. After the last frame the server closes with 1000. |
| Frame | Meaning |
|---|---|
{"type":"tick","seq":…,"text":…,"severity":…,"ts":…} | seq from 1; the text follows one fixed list. |
{"type":"pause"} / {"type":"resume"} | Answered with paused / resumed. |
{"type":"error","code":"bad_param",…} | A parameter out of range; the feed does not start. |
How to call it from your tools
Five frames, one per second
Halls – Socket.IO
The same halls over Socket.IO v4: join with an acknowledgement, then send and receive message events.
| Direction | Event | Data |
|---|---|---|
| you emit (with acknowledgement) | join | {"room":"…"} → ack {"ok":true,"room":…,"users":…} or {"ok":false,"error":"room_not_found"} |
| you emit | message | {"text":"…"} |
| you get | joined | {"room":…,"users":…} |
| you get | message | {"user":…,"text":…,"ts":…} |
Socket.IO v4, path /socket.io, namespace /chat. Send your token as auth: {token} or ?token=; without it the connection fails with connect_error Unauthorized.
How to call it from your tools
Socket.IO URL (Postman: New > Socket.IO)
Watch-post – Server-Sent Events
The watch-post's lines as an event stream over plain HTTP, with ids you can resume from.
| Line | Meaning |
|---|---|
retry: 3000 | Reconnect after 3 seconds (sent first). |
id: n | The event number; send it back as Last-Event-ID to resume after it. |
event: tick | The event name. |
data: {…} | The same JSON as the WebSocket feed. |
How to call it from your tools
Five events
Resume after event 3 (with your token, so it counts for your task)
Bridge webhooks
Fire a bridge event at your own receiver and read what arrived: a signed body, delivered twice with one event_id.
| Request | What it does |
|---|---|
GET /api/webhooks | Your receiver: its id, URL and signing secret. |
POST /api/webhooks/fire | {"event":"raven.delivered"} → the server POSTs a signed event to your receiver, twice, with one event_id. |
GET /api/webhooks/deliveries | What your receiver got: the last 20, newest first. |
POST /hooks/<receiver_id> | Your receiver. Anything you send there is stored too. |
How to call it from your tools
Fire an event
Your deliveries
Bifrost carries messages between the worlds: ravens you can follow, an echo stone, halls where Huginn answers, a watch-post that calls out what it sees, and a receiver for the bridge's own webhooks. Every door is yours alone; nobody else reads your messages.
Addresses
Sign in on the right first: most calls need your token- WebSocket
- WebSocket echo
- WebSocket chat
- WebSocket feed
- SSE stream
- REST base URL – sign-in, orders, keys