Sblurp

Protocol and transport

A community server speaks Connect RPC over HTTP. The contract is one file, proto/sblurp/v1/sblurp.proto. The web client, the example bot and any client you write use the same API.

Calls

Each call is an HTTP POST to {base}/sblurp.v1.{Service}/{Call}. {base} is the server's base URL, such as https://chat.example.com.

curl https://chat.example.com/sblurp.v1.ServerService/GetServerInfo \
  -H 'Content-Type: application/json' -d '{}'

The body is JSON (application/json) or binary protobuf (application/proto). gRPC and gRPC-Web clients work too. JSON follows protojson:

  • Field names are lowerCamelCase, such as channelId. The proto names, such as channel_id, are accepted too.
  • 64-bit numbers (int64) are strings, such as "size": "14211".
  • Enums are their names, such as "MEMBER_ROLE_ADMIN".

Services

Service What
ServerService Server info, joining, profile, state, the event stream, moderation, invites, settings, roles, custom emoji.
ChatService Channels, messages, reactions, read state, typing, search, private channel members, channel access.
BotService Make, list, rotate and delete bots.

Shared messages and enums are on the Types page. These four pages are generated from the proto file and its comments. The same contract, with every call, field number and comment, is in schema.json for tools and agents, and as OpenAPI 3.1 in openapi.json. Browse and try every call in the API explorer.

Authentication

Every call except GetServerInfo needs a header:

Authorization: Bearer <token>

The token is a sign-in token from a trusted issuer, made for this server, or a bot token (sbb_...). See Sign-in and tokens.

A person who signed in but has not joined may call only GetServerInfo and Join. Other calls return permission_denied.

A client's first calls

  1. GetServerInfo: name, icon, whether it is invite only, join questions. No token needed.
  2. Join: once, with the profile the person agreed to share.
  3. GetState: the sidebar. Channels, members, read states, roles, and the current seq.
  4. Subscribe with afterSeq = that seq: live events.
  5. Unary calls such as SendMessage to act.

Streaming

Subscribe is a server stream. Browsers support server streams over Connect. There is no bidirectional stream: clients send with unary calls. See Events.

Plain HTTP endpoints

Uploads, files, custom emoji, invite links and the health check are plain HTTP. See Uploads and files.

CORS

A server allows any origin, because any client may connect to any server.

Versioning

Servers upgrade on their own schedule, so one client talks to many server versions. The proto follows these rules:

  • A field number is never renumbered or reused. Removed ones are reserved.
  • New fields are optional in meaning: an old peer ignores them.
  • protocol_version goes up only for a change an old client cannot ignore. It is 1 today, and GetServerInfo reports it.

View this page as Markdown · Glossary · API schema.json · openapi.json