Fluxer API
Fluxer is a self-hostable chat platform. Its API has four surfaces, and all four share one identifier space.
- To build a client or a bot, start with the HTTP API and the Gateway.
- For voice or a screen share, read Voice.
- To run an instance, start with Get started.
- To look up one route, use the sidebar or the Protocol surfaces table.
Protocol surfaces
Section titled “Protocol surfaces”| Surface | What it is | Reference |
|---|---|---|
| HTTP API | Resource reads and mutations below /v1 | HTTP API |
| Gateway | A persistent WebSocket for session state and real-time events | Gateway |
| Media Proxy | Attachments, image assets, themes, entrance sound audio, and the upload relay | Media Proxy |
| Admin API | The privileged namespace below /v1/admin | Admin API |
A client mutates a resource over the HTTP API and receives the resulting update as a Gateway Dispatch. Each operation states the Dispatches it fires, and Events defines each payload and its recipient scope.
A snowflake is the identifier all four surfaces share. Voice runs on LiveKit, and Voice defines the placement protocol and the media transport.
Shared contracts
Section titled “Shared contracts”| Read this | For |
|---|---|
| Conventions | Wire table notation, footnotes, omission and null |
| Authentication | The Authorization grammar and the four credential kinds |
| Snowflakes | Identifiers, ordering, and pagination cursors |
| Errors | The error envelope and the code registries |
| Rate limits | Buckets, the 429 body, and the X-RateLimit-* headers |
| Locales | The locale registry and Accept-Language negotiation |
Endpoint discovery
Section titled “Endpoint discovery”A client that knows only a Fluxer origin sends GET /.well-known/fluxer first. The route is unversioned, accepts no credential, and is readable from any origin.
GET https://example.com/.well-known/fluxerThe instance Fluxer hosts answers discovery at https://fluxer.app/.well-known/fluxer. That origin is the one thing a client is given.
The response is the instance discovery object. Every base URL a client uses comes from the instance endpoints object inside it. A client MUST read every base URL from that response, and it MUST NOT derive one from the origin it was given or assume an official Fluxer domain.
The base URL a client takes depends on its kind.
endpoints.api_publicis the endpoint a bot, a library, or any other third-party client uses.endpoints.api_clientis the endpoint the first-party web application uses.endpoints.apirepeatsendpoints.api_client.
A credential goes in the Authorization header.
GET https://api.example.com/v1/users/@meAuthorization: flx_ZDb1GURItsMuYl1zvrgxv2qLBxyNmgNSEaWTThat credential is a user session token. Log in with a password issues one. A bot sends a bot token with the Bot prefix, issued by Create application. Authentication gives the exact form of all four kinds.