This API is designed for the application’s own browser client and is not
versioned for external consumers. Endpoint shapes can change between releases.
For automation, prefer
/api/health and /api/setup, which are stable.Authentication
Most endpoints require a session cookie issued at login and signed withBETTER_AUTH_SECRET. Requests are authorized per record: handlers verify that
the authenticated user owns the object being accessed.
Public endpoints
Public
Liveness and readiness probe. Executes
select 1 against PostgreSQL.Returns 200 {"ok":true} when healthy and 503 {"ok":false} when the
database is unreachable.Public
Reports installation setup state.
required is true only when setup has not completed and no users exist.Public, one-time
Creates the first administrator in a single transaction and permanently closes
public setup.Returns
403 when the claim token does not match.Public
Branding, setup state, and SSO button configuration needed before login.
Served with
cache-control: no-store. Contains no credentials or user data.Public
Authentication routes: sign-in, sign-out, session, and OIDC callbacks at
/api/auth/oauth2/callback/<provider-key>.Session endpoints
Session
The current user’s profile and role.
Session
Lists the user’s providers. API keys are never returned; each provider carries
a
hasApiKey flag. Custom headers are decrypted and returned so they
remain editable.Session
Creates a provider from a name, base URL, optional API key, and optional
headers.
Session
Updates a provider. Omitting the API key leaves the stored one unchanged.
Session
Deletes a provider and its models. If it owned the default model, the oldest
remaining enabled model is promoted.
Session
Validates a provider by requesting
<base URL>/models through the outbound
guard.Session
Creates a model with a provider model ID, display name, context window, and
maximum output tokens. The first model becomes the default.
Session
Updates a model, including making it the default or toggling
enabled.
Default changes release the previous holder first.Session
Deletes a model, promoting a replacement default when needed.
Session
Lists the user’s conversations.
Session
Creates a conversation.
Session
Updates a conversation, such as renaming it or starting a fresh context.
Session
Deletes a conversation and its messages.
Session
The streaming chat endpoint. Resolves the model, decrypts credentials, ensures
the workspace is running, and streams text, reasoning, and tool calls back to
the browser. Messages and tool results are persisted as they complete.
Session
Lists configured MCP servers and their known tools.
Session
Adds an MCP server, connects to it, lists tools, and records a fingerprint of
their definitions.
Session
Updates an MCP server, including re-approving changed tool definitions.
Session
Removes an MCP server.
Workspace endpoints
Session
Current workspace phase:
running, starting, stopped, or disabled, plus
a readiness flag and the mode.Session
Starts the workspace and waits for readiness.
Session
Requests an immediate scale to zero, clearing active leases.
Session
Lists or previews files under the home directory. Confined to canonical paths;
traversal and symlink escapes are rejected.
Session
Uploads a file, normally into
~/artifacts.Session
Authenticated download of a workspace file, proxied through the control plane.
Admin endpoints
Admin
Lists all users.
Admin
Creates a user account directly.
Admin
Updates a user’s role or enabled state.
Admin
Returns branding and OIDC configuration. Client secrets are not returned in
plaintext.
Admin
Updates branding and OIDC configuration.
Admin
Validates OIDC discovery and client credentials against the real provider
before enabling it.
Admin
Creates an invitation for a new account.
Public
Redeems an invitation to create an account.
Workspace-authenticated endpoints
Workspace
Backs the
r5dchat conversation commands. Authenticates with the workspace
bearer identity, then re-checks that the workspace’s user owns the requested
conversation. Supports overview, single-turn, and full-read modes in Markdown
or JSON.Errors
Errors return a JSON body with a machine-readable code:Monitoring
Use/api/health for liveness and readiness. It is unauthenticated and checks
database connectivity, making it a meaningful signal rather than a static
response.