How-to

A quick guide to sending and receiving messages with your tenant. The commands below are filled in with your base URL and tenant UUID — copy and paste them as-is.

How it works

A channel holds the most recent JSON message posted to it. POST a message to publish it; GET returns the last message, or streams live events if you ask for an event stream. A channel name must match one of your topic patterns (e.g. a test* rule would match test1); add rules on the Topics page. Channel names may use letters, digits, ., _ and -.

Messages are ephemeral. A channel keeps only the last message, and holds it for up to 24 hours — but it may be evicted sooner, so treat reads as best-effort.

1. Send a message

POST a JSON body (≤ 5000 bytes). A successful publish returns 202 Accepted.

…

2. Read the latest message

GET returns the last message as JSON, or 204 No Content if nothing has been posted yet.

…

3. Stream live events

Add Accept: text/event-stream to receive a Server-Sent Events stream. It starts with the last message (if any), then delivers each new message as it arrives.

…

4. Authenticating

A channel whose topic rule has no token is open — no Authorization header is needed. Otherwise send the channel's write token (to post) or read token (to read) as a bearer token. Configure these on the Topics page.

…

You can also use an API token as the bearer. Its value is <tenant-uuid>:<secret> — created once on the Tokens page (the secret is shown only at creation time).

Limits & responses

• Payloads must be valid JSON and at most 5000 bytes.
• Per-tenant rate limits: 100 requests/second and 1000/minute (over the limit returns 429 Too Many Requests).
• Common responses: 202 published, 204 no message yet, 200 message returned, 400 bad request, 401 unauthorized, 404 no such channel, 413 payload too large, 429 rate limited, 503 active-channel limit reached.

Admin API reference

These endpoints manage your tenant and are separate from the public pub/sub API above. They require an API token with the admin scope, sent as Authorization: Bearer <uuid>:<secret> (the web console uses your signed-in session instead). <uuid> is your tenant UUID.

Click an endpoint for example request/response JSON.

{
  "id": "11111111-1111-1111-1111-111111111111",
  "name": "Acme",
  "email": "you@example.com",
  "tokens": [
    { "id": "k3f9c2", "name": "my-app", "scopes": ["admin"], "used_days_last_7": 3 }
  ],
  "usage": {
    "topic_rules": { "count": 2, "limit": 1000 },
    "api_tokens": { "count": 1, "limit": 50 },
    "active_channels": { "count": 0, "limit": 1000 }
  }
}

{ "topics": [ { "pattern": "news.*", "write": "wtok", "read": "" } ] }

{ "topics": [ { "pattern": "news.*", "write": "wtok", "read": "" } ] }

{ "topics": [ { "pattern": "news.*", "write": "wtok", "read": "" } ] }

{ "pattern": "news.*", "write": "wtok", "read": "" }

{ "topics": [ { "pattern": "news.*", "write": "wtok", "read": "" } ] }

{ "pattern": "news.*", "write": "new-wtok", "read": "" }

{ "topics": [ { "pattern": "news.*", "write": "new-wtok", "read": "" } ] }

{ "pattern": "news.*" }

{ "topics": [] }

{ "tokens": [ { "id": "k3f9c2", "name": "my-app", "scopes": ["admin"], "used_days_last_7": 3 } ] }

{ "name": "my-app", "scopes": ["admin"] }

{
  "id": "k3f9c2",
  "name": "my-app",
  "scopes": ["admin"],
  "credential": "11111111-1111-1111-1111-111111111111:SECRET",
  "authorization": "Bearer 11111111-1111-1111-1111-111111111111:SECRET"
}

{ "id": "k3f9c2" }

{ "deleted": "k3f9c2" }

{
  "entries": [
    {
      "ts": "2026-06-15T00:00:00Z",
      "ip": "203.0.113.7",
      "tenant": "11111111-1111-1111-1111-111111111111",
      "email": "you@example.com",
      "action": "create topic",
      "topic": "news.*"
    }
  ]
}

{ "channels": ["news.sports", "news.weather"] }