| title | API surface | |||||
|---|---|---|---|---|---|---|
| summary | Human-oriented map of REST, realtime, Git HTTP, and administration endpoints. | |||||
| status | current | |||||
| type | reference | |||||
| scope | community | |||||
| audience |
|
|||||
| topics |
|
|||||
| related |
|
|||||
| code_paths |
|
The Rust service exposes browser APIs, WebSocket collaboration, and Git smart
HTTP from the same origin. The generated REST authority is
protocol/openapi.json; Rust operations and wire
schemas originate in backend/src/protocol/, and browser declarations are
generated into web/src/lib/api/generated.ts. This page summarizes product
policy and does not replace that machine-readable contract.
Ordinary /v1 failures use the JSON envelope
{ "code": "...", "message": "...", "request_id": "..." }. code is stable
and intended for control flow; message is diagnostic text and request_id
correlates the response with server logs. Git smart HTTP retains its native
protocol error bodies. Regeneration and compatibility rules are documented in
Application protocols.
The first-party API client sends x-toss-protocol-epoch on /v1 requests, and
Core echoes it. An explicit mismatch returns HTTP 426 with
code: "client_incompatible" before route handling. Missing values remain
valid for non-Web clients; this fence is not a public API version.
GET /healthGET /ready
GET /v1/experienceGET /v1/helpGET /favicon.icoGET /v1/product-assets/faviconGET /v1/product-assets/touch-iconGET /v1/auth/configPOST /v1/auth/local/loginPOST /v1/auth/local/registerGET /v1/auth/oidc/loginGET /v1/auth/oidc/callbackGET /v1/auth/gitlab/loginGET /v1/auth/gitlab/callbackGET /v1/auth/external-git/{provider_id}/loginGET /v1/auth/mePOST /v1/auth/logout
GET /v1/auth/config returns sanitized runtime policy and distribution fields,
including distribution_id, enabled_project_types, product branding,
anonymous-access policy, an ordered identity_providers list, and nullable
ai_assistant connection-policy display metadata. A user-defined policy returns
only its kind. A managed policy returns provider ID/label, effective default
recommendation ID, effective recommendation IDs/upstream IDs/labels, and the
non-secret custom-profile defaults, limits, catalog-match rule, and saved-count
bound. It deliberately omits the managed base URL, credential label, protocol
details, recommendation execution parameters, live catalog, user selection,
and saved personal profiles.
It never returns config paths, client secrets, token encryption keys, or
credentials.
GET /v1/experience returns product identity, localized landing content, and
resources visible to the current request. GET /v1/help returns localized
Markdown topics plus the same filtered resources. Both endpoints are public,
but entries marked authenticated in the distribution are returned only when
the request carries a valid session. Their responses use Cache-Control: private, no-store and Vary: Cookie, Authorization. Product asset responses
are passive, size-bounded distribution files and are sent with nosniff.
The oidc and gitlab login/callback route pairs currently drive the same
configured OIDC client. They are naming aliases, not independent providers.
The parameterized login route starts a configured external-provider login such
as a GitHub App web flow. It returns through the provider instance's shared
/v1/external-git/providers/{provider_id}/callback route. Only instances with
login enabled appear in identity_providers.
GET /v1/realtime/auth/{project_id}GET /v1/realtime/ws/{doc_id}?project_id={uuid}&collaboration_revision={revision}&protocol_epoch={epoch}GET /v1/realtime/projects/{project_id}?protocol_epoch={epoch}
The WebSocket handshake accepts an authenticated session, share token, or named
guest. Core authorizes before upgrade, then revalidates after room subscription
and before bootstrap. Epoch mismatch closes with code 4406; service drain
uses 1012.
Event kinds include:
bootstrap.done;yjs.sync,yjs.update, andyjs.ack;presence.join,presence.leave,presence.meta, andpresence.cursor;workspace.changedafter a committed document, tree, settings, or asset mutation; the payload contains ascope, nullable affectedpath, and a collaboration revision for document changes;document.changedwhen an open document binding has been superseded by a newer collaboration revision;access.changedwhen project authorization must be revalidated;project.replacedwhen destructive repository materialization changes the collaboration generation;server.errorfor persistence failures.
Server events contain doc_id, user_id, kind, payload, and an RFC 3339
at timestamp. Events originating from a live client connection also contain
connection_id; presence is maintained per connection and displayed per
member, so closing one of a member's tabs does not remove their other active
tabs. The editor keeps the collaborator count deduplicated by member and shows
a separate editing-session count when one member has multiple live connections.
Read-only peers participate in presence but cannot send document updates.
Access changes close the current stream and invalidate the browser's cached
project capabilities, causing a page reload through fresh authorization.
Resynchronization errors close only the affected stream and reconnect through
a new bootstrap.
Malformed or unknown events are ignored by the browser.
GET|POST /v1/organizationsGET /v1/organizations/mineGET|POST /v1/projectsPATCH /v1/projects/{project_id}POST /v1/projects/{project_id}/copyGET|PATCH /v1/projects/{project_id}/archiveGET|PUT /v1/projects/{project_id}/thumbnail
POST /v1/projects and project copy enforce the active distribution's
enabled_project_types. A Typst-only distribution accepts only Typst projects.
GET /v1/templatesGET /v1/templates/builtin/{template_id}/thumbnailPOST /v1/templates/builtin/{template_id}/projects
All Gallery routes require authentication. The catalog response combines deployment-owned built-ins with accessible personal and organization-shared project templates. Each item identifies its source, localized metadata, project type, thumbnail state, owner when applicable, and whether the current user may edit the source project.
Built-in instantiation accepts a project name and creates an independent normal
project from the configured directory tree. Personal/shared templates continue
to use POST /v1/projects/{project_id}/copy; project-template and organization
permissions remain enforced by that path.
GET /v1/projects/{project_id}/treePOST /v1/projects/{project_id}/filesPATCH /v1/projects/{project_id}/files/moveDELETE /v1/projects/{project_id}/files/{path}GET /v1/projects/{project_id}/settingsPATCH /v1/projects/{project_id}/settings/entry-filePATCH /v1/projects/{project_id}/settings/latex-engineGET|POST /v1/projects/{project_id}/documentsPUT /v1/projects/{project_id}/documents/by-path/{path}GET|PUT|DELETE /v1/projects/{project_id}/documents/{document_id}
GET|POST /v1/projects/{project_id}/assetsGET|DELETE /v1/projects/{project_id}/assets/{asset_id}GET /v1/projects/{project_id}/assets/{asset_id}/rawPOST /v1/projects/{project_id}/pdf-artifactsGET /v1/projects/{project_id}/pdf-artifacts/latest
Uploads are bounded by MAX_REQUEST_BODY_BYTES. Asset authorization always
uses the containing project, including raw-content responses. PDF upload bodies
are base64 encoded and the resulting bytes are currently stored in PostgreSQL.
GET /v1/processing/capabilitiesGET /v1/projects/{project_id}/processing/capabilitiesPOST /v1/projects/{project_id}/buildsPOST /v1/projects/{project_id}/exports/pptxPOST /v1/imports/pptx?filename={filename}&input_profile={profile}GET /v1/processing/jobsGET /v1/processing/jobs/{job_id}POST /v1/processing/jobs/{job_id}/cancelGET /v1/processing/jobs/{job_id}/artifacts/{artifact_id}
The default Community distribution enables only latex.compile.pdf/v1.
Community also defines generic PPTX import/export routes and finalizers for
deployments that allow those operations and configure compatible processors.
Every submission requires authentication and an Idempotency-Key; project
commands additionally require current read access and a matching project type.
A new job returns 202, while an exact replay returns the existing job.
The global capability response contains only distribution-allowed,
deployment-configured operations and distinguishes available from
configured-but-offline waiting. The project capability route filters by
project type and reports the current worker availability. An absent operation
is not enabled.
PPTX import uses a bounded raw PPTX body. A distribution may advertise a closed
set of input profiles through processing capabilities; clients omit
input_profile when none are configured. Import creates a new Typst project
only after Core validates the worker's Workspace bundle, and its terminal job
exposes result_project_id. PPTX export accepts no body, snapshots a Typst
project, and publishes a downloadable PPTX artifact; processors cannot mutate
the source project.
Job lists are requester-owned and recheck current project access. Cancellation is allowed during preparation, queueing, and active execution, but not after Core accepts delivery into finalization. Artifact downloads reauthorize the requester and containing project on every request. Internal worker routes and their separate generated contract are documented in Worker protocol; browser clients must not call them.
GET|POST /v1/projects/{project_id}/revisionsGET /v1/projects/{project_id}/revisions/{revision_id}/documents
Revision IDs are local Git commit OIDs. Revision document responses support incremental anchors used by the workspace to avoid retransferring unchanged files/assets when moving between nearby history states.
GET|POST /v1/projects/{project_id}/rolesGET /v1/projects/{project_id}/access-usersGET /v1/projects/{project_id}/organization-accessPUT|DELETE /v1/projects/{project_id}/organization-access/{org_id}GET|POST /v1/projects/{project_id}/group-rolesDELETE /v1/projects/{project_id}/group-roles/{group_name}PUT /v1/projects/{project_id}/templateGET /v1/projects/{project_id}/template-organization-accessPUT|DELETE /v1/projects/{project_id}/template-organization-access/{org_id}GET|POST /v1/projects/{project_id}/share-linksDELETE /v1/projects/{project_id}/share-links/{share_link_id}GET /v1/share/{token}/resolvePOST /v1/share/{token}/joinPOST /v1/share/{token}/temporary-login
Share-link redemption by a signed-in user creates a durable project role. Named temporary guests receive a scoped, expiring project session. Revoking a link prevents new use; project roles already granted to authenticated users remain visible to the project owner.
GET /v1/typst/packages/{namespace}/{name}/{version}GET /v1/typst/builtin/{path}GET /v1/latex/texlive/{path}
The package endpoint accepts exact local and preview package identities.
local resolves only validated entries in the active distribution catalog and
never falls back to a public registry. preview resolves an immutable catalog
seed, then the validated cache, then the configured Typst Universe source when
enabled. Successful responses include the archive SHA-256 digest. The LaTeX
TeXLive endpoint returns 404 when the active distribution does not enable LaTeX. Typst package,
built-in asset, and TeXLive requests require an authenticated user session; a
named temporary guest session alone is not sufficient. See
Community LaTeX runtime for proxy/cache limits.
GET /v1/git/status/{project_id}GET /v1/git/repo-link/{project_id}GET|POST /v1/git/repo/{project_id}/{rest}
Git transport requires a personal access token as the HTTP password. Clone and fetch require project read access; push requires the project owner. Force pushes and stale non-fast-forward updates are rejected.
GET|DELETE /v1/external-git/providers/{provider_id}/connectionGET /v1/external-git/providers/{provider_id}/authorizeGET /v1/external-git/providers/{provider_id}/callbackGET /v1/external-git/providers/{provider_id}/ownersGET /v1/external-git/providers/{provider_id}/repositoriesGET /v1/external-git/providers/{provider_id}/repositories/{repository_id}/branchesPOST /v1/external-git/importsGET /v1/external-git/jobs/{job_id}GET /v1/projects/{project_id}/external-git/statusGET /v1/projects/{project_id}/external-git/branchesPOST /v1/projects/{project_id}/external-git/createPOST /v1/projects/{project_id}/external-git/linkPOST /v1/projects/{project_id}/external-git/unlinkPOST /v1/projects/{project_id}/external-git/checkpointPOST /v1/projects/{project_id}/external-git/sync
The public API uses validated provider-instance IDs and never accepts an
arbitrary clone URL. GitHub, GitLab, Gitea, and Forgejo adapters are
implemented; Codeberg uses the Forgejo protocol with explicit Codeberg brand
metadata. A deployment may configure more than one instance, including
multiple instances of one provider kind. Unlinked project operations and
imports carry an explicit provider-instance ID; linked project operations use
the provider persisted on the link. Import creates a new
project from a repository branch; sync is owner-only and replaces a linked
project from a selected branch. Checkpoint is owner-only and targets the
distribution-managed branch. Status values include dirty, pending,
syncing, retry_wait, active, unlinked, reauth_required, conflict,
and error.
Normal editing never calls either synchronization direction automatically.
Inbound operations return 202 with a durable job resource. The worker fetches
Git LFS, validates paths and configured size limits, stages assets, then applies
the complete project snapshot atomically.
Document upserts include X-Project-Content-Epoch, obtained from the project
tree response. A stale or missing generation is rejected so an editor opened
before a branch replacement cannot write the previous document back afterward.
GET|POST /v1/profile/security/tokensDELETE /v1/profile/security/tokens/{token_id}
Personal access-token plaintext is returned once at creation. Tokens may expire and record their last successful use.
GET|PUT /v1/admin/settings/authGET|POST /v1/admin/orgs/{org_id}/oidc-group-role-mappingsDELETE /v1/admin/orgs/{org_id}/oidc-group-role-mappings/{group_name}
Admin settings include managed_fields. Values owned by a distribution or
deployment policy are visible but read-only in the UI.