Server API

Two surfaces. REST handles uploads, downloads and a few things that want plain HTTP caching. Everything interactive runs over Socket.IO: chat, presence, voice signalling, moderation, settings.

There are no authentication endpoints here. Identity comes from an account issuer or from a keypair on the device, and joining is a signed challenge over the socket. See Identity.

REST

Default port 5000. Endpoints marked Bearer want Authorization: Bearer <accessToken>.

Public

What /info returns

{
  "serverId": "...",
  "name": "...",
  "description": "...",
  "members": "12",
  "lanOpen": false,
  "identityTiers": ["account"],
  "joinPolicy": "invite"
}

identityTiers and joinPolicy are deliberately unauthenticated. The point is that a client can say "you don't need an account for this one" before anybody tries, and neither field tells a caller anything they could not learn by attempting the join and reading the refusal.

Two things depend on who is asking. A server whose discoverable setting is off answers 404 to anybody who isn't already a member, so it disappears rather than advertising itself. And version is only included for members, because a precise build number lets anyone on the network scan for hosts running a version with a known vulnerability, and this endpoint has to stay open for the add-server flow.

Messages

Sending is chat:send over the socket. There's no POST here.

Uploads

Server

GRYT_SERVER_ICON_MAX_MB caps the upload, 25 MB by default. PNG, JPEG, WebP, GIF, AVIF and SVG are accepted; SVG is sanitised before it's stored.

Members

Emojis

Importing emojis

From BetterTTV:

From emoji.gg:

The file routes fetch the image server-side and return the bytes, so the browser isn't the thing talking to BetterTTV or emoji.gg.

Link previews and media

Webhooks

The management API

A separate listener on GRYT_ADMIN_PORT (5099), started only when GRYT_ADMIN_TOKEN is set, published to loopback only. It exists so somebody administering the machine can change database-backed settings without being the server's owner.

Authorization: Bearer <GRYT_ADMIN_TOKEN> on all three. Requires server 1.5.0. A PATCH goes through the same apply path as a change made from a client, so it withdraws mDNS advertising, drops caches and writes an audit entry rather than only updating a row.

Socket.IO

Joining

The handshake is three messages, and it's a signature exchange rather than a password.

The server also proves itself, over server:identify, as a connection-level exchange rather than part of the join. A client reconnecting with a saved token never joins at all, so a proof carried on join would leave the common path handing a bearer token to a server nobody authenticated.

Refusals come back on server:error with a reason: invite_required, invalid_invite, invite_rate_limited, identity_tier_refused, identity_verification_failed, challenge_expired, nonce_mismatch, account_already_member, approval_pending, auth_required, auth_disabled, auth_misconfigured, join_refused, join_failed, invalid_nickname.

Sessions and tokens

Chat

Direct messages

A conversation between two people, or a group. dm:open is idempotent — asking twice for the same pair returns the conversation that already exists.

Calls

Ringing only. The call itself is voice, and goes through the events above.

Threads

A thread hangs off one message. thread:create names the message it grows from.

Forums

A forum channel is threads with a topic list in front of them, so the events here sit on top of the thread events above.

Voice

Members, profile and presence

Moderation

Administration

Diagnostics