Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

REST API

All endpoints are served under /api unless noted otherwise. Session cookies and CSRF headers are required for non-authenticated GET requests when features.auth_v1 is enabled. The OpenAPI schema is generated from rustygpt-server/src/openapi.rs and can be exported with cargo run -p rustygpt-cli -- spec.

Setup

MethodPathDescription
GET/api/setupReturns { "is_setup": bool } by calling is_setup() in PostgreSQL.
POST/api/setupCreates the first administrator account (see scripts/pg/procs/010_auth.sql::init_setup). Subsequent calls return 400.

Authentication

MethodPathDescription
POST/api/auth/loginEmail/password login. Returns LoginResponse with session + CSRF cookies.
POST/api/auth/logoutRevokes the current session. Requires CSRF header.
POST/api/auth/refreshRotates session cookies inside the idle window.
GET/api/auth/meReturns MeResponse (requires authenticated session).

OAuth helpers

Handlers in handlers/github_auth.rs and handlers/apple_auth.rs expose optional OAuth flows when credentials are present:

MethodPathNotes
GET/api/oauth/githubReturns an authorization URL based on GITHUB_* environment variables.
GET/api/oauth/github/callbackExchanges the code for a session via ProductionOAuthService.
POST/api/oauth/github/manualDeveloper helper that accepts a raw auth code.
GET/api/oauth/appleSame as GitHub but for Apple.
GET/api/oauth/apple/callbackCallback handler.
POST/api/oauth/apple/manualManual exchange helper.

Conversations & membership

Routes implemented in handlers/conversations.rs:

MethodPathDescription
POST/api/conversationsCreate a new conversation.
POST/api/conversations/{conversation_id}/participantsInvite/add a participant. Emits membership + presence SSE events.
DELETE/api/conversations/{conversation_id}/participants/{user_id}Remove a participant.
POST/api/conversations/{conversation_id}/invitesCreate an invite token.
POST/api/invites/acceptAccept an invite token.
POST/api/invites/{token}/revokeRevoke an invite token.
GET/api/conversations/{conversation_id}/threadsList thread summaries (supports after + limit query params).
GET/api/conversations/{conversation_id}/unreadReturn unread counts per thread.

Threads & messages

Routes from handlers/threads.rs:

MethodPathDescription
GET/api/threads/{root_id}/treeDepth-first thread slice (cursor_path + limit optional).
POST/api/threads/{conversation_id}/rootCreate a new thread root. Triggers assistant streaming when role = assistant.
POST/api/messages/{parent_id}/replyReply to an existing message.
GET/api/messages/{message_id}/chunksRetrieve persisted assistant chunks.
POST/api/threads/{root_id}/readMark thread as read (MarkThreadReadRequest).
POST/api/messages/{message_id}/deleteSoft-delete a message.
POST/api/messages/{message_id}/restoreRestore a previously deleted message.
POST/api/messages/{message_id}/editReplace message content.
POST/api/typingSet typing state (TypingRequest).
POST/api/presence/heartbeatUpdate presence heartbeat.

Streaming

MethodPathDescription
GET/api/stream/conversations/{conversation_id}SSE endpoint producing ConversationStreamEvent values. Requires session cookie and (optionally) Last-Event-ID.

Copilot-compatible endpoints

These helpers live in handlers/copilot.rs and provide simple echo responses for integration tests:

MethodPathDescription
GET/v1/modelsReturns ModelsResponse with two static models (gpt-4, gpt-3.5).
POST/v1/chat/completionsEchoes provided messages as assistant responses (ChatCompletionResponse).

Admin rate limit API

Available when features.auth_v1 = true and rate_limits.admin_api_enabled = true (handlers/admin_limits.rs):

MethodPathDescription
GET/api/admin/limits/profilesList profiles.
POST/api/admin/limits/profilesCreate a profile.
PUT/api/admin/limits/profiles/{id}Update profile parameters/description.
DELETE/api/admin/limits/profiles/{id}Delete a profile (fails if still assigned).
GET/api/admin/limits/assignmentsList route assignments.
POST/api/admin/limits/assignmentsAssign a profile to a route.
DELETE/api/admin/limits/assignments/{id}Remove an assignment.

Health and observability

Outside of the /api prefix, the server exposes:

MethodPathDescription
GET/healthzLiveness probe.
GET/readyzReadiness probe (verifies PostgreSQL bootstrap).
GET/metricsPrometheus metrics via metrics-exporter-prometheus.
GET/.well-known/{path}Served when features.well_known = true; entries configured via [well_known.entries].
GET/openapi.json / /openapi.yamlGenerated OpenAPI spec.

Refer to Authentication for cookie details and Configuration for the relevant keys.