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 reads endpoint discovery first. GET /.well-known/fluxer 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. Every base URL below it still comes from the response.
It returns 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.
Take the base URL for the kind of client being built, then send a credential in the Authorization header. A bot, a library, or any other third-party client takes endpoints.api_public. endpoints.api_client is the endpoint the first-party web application uses, and endpoints.api repeats it.
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.