API Reference

This page lists the main HTTP routes of SelfDocHub, grouped by purpose, with the access they require. All paths are relative to your instance address.

Authentication#

Kind Header Used for
User session Authorization: Bearer <session token> from POST /login Everything under /api/v1/... except the public routes below
Service upload token Authorization: Bearer <service token> Publishing a specification
MCP token Authorization: Bearer <mcp secret> /mcp

Access levels used below: public (no session), session (any signed-in user with access to the service), editor (admin or editor), admin. Slug-scoped routes also apply team scoping. A route that needs a license feature answers 402 when the license lacks it.

Public and health#

Method and path Access Purpose
GET /healthz, GET /readyz public Health checks
GET /api/v1/license public License status (device ID, dates)
GET /api/v1/i18n/{lang} public Translation bundle (default for the configured language)
GET /api/v1/auth/providers public Enabled SSO providers for the login page
POST /login, POST /logout public Sign in and out (with the /login/2fa/... steps)

Publishing and versions#

Method and path Access Purpose
POST /api/v1/services/{slug}/spec service token Publish a specification (?branch=)
POST /api/v1/services/{slug}/versions/import editor Import a version from a session
GET /api/v1/services/{slug}/versions session List versions, newest first
GET /api/v1/services/{slug}/versions/{id} session Read a stored specification
GET /api/v1/services/{slug}/versions/{id}/changelog session One version's Change Log
GET /api/v1/services/{slug}/versions/changelog/search?q= session Search Change Logs
POST /api/v1/services/{slug}/versions/{id}/promote admin Make a version current
PATCH /api/v1/services/{slug}/versions/{id} admin Change a version's display number
POST /api/v1/services/{slug}/versions/{id}/reparse admin Reparse a stored version
DELETE /api/v1/services/{slug}/versions/{id} editor Delete a non-current version
GET/PUT/DELETE /api/v1/services/{slug}/version-pin session Personal working version

Reading documentation#

Method and path Access Purpose
GET /api/v1/navigation session Menu tree and the current user
GET /api/v1/search?q= session Search (up to 60 results, minimum length from search_min_length)
GET /api/v1/merged/{slug} session A service's merged document
GET /api/v1/services/{slug}/endpoint-schema?method=&path= session One operation with only the schemas it uses
GET /api/v1/services/{slug}/endpoint-schema/example session Generated example request body
GET /api/v1/services/{slug}/rpc-method-schema?name= session One OpenRPC method
GET /api/v1/services/{slug}/asyncapi-operation-schema?id= session One AsyncAPI operation
GET /api/v1/services/{slug}/tags/{tag} session A tag's description

Content editing#

Method and path Access Purpose
GET/PUT/DELETE /api/v1/services/{slug}/overlay editor Service, tag or operation overlay
GET/PUT /api/v1/services/{slug}/parameter-overlays editor Parameter and field overlays (plus /history routes)
GET /api/v1/overlays/orphaned, DELETE /api/v1/overlays/orphaned/{id} editor Orphaned overlays
GET/PUT/DELETE /api/v1/services/{slug}/navigation-order editor Service structure tree
GET/POST /api/v1/services/{slug}/pages list: session, create: editor Text pages
GET/PUT/DELETE /api/v1/services/{slug}/pages/{id} read: session, write: editor One text page
GET/PUT/DELETE /api/v1/services/{slug}/labels read: session, write: editor Labels

Try-It and personal data#

Method and path Access Purpose
/api/v1/try/{slug} session The Try-It proxy
GET/POST /api/v1/services/{slug}/environments, PUT/DELETE .../environments/{id} session (edit and delete: creator or admin) Environments
GET/POST /api/v1/services/{slug}/tryit-requests, DELETE .../tryit-requests/{id} session Saved requests
POST /api/v1/services/{slug}/tryit-requests/share, GET /api/v1/tryit-requests/shared/{id} session Shared links
GET/POST /api/v1/services/{slug}/interactions, GET/DELETE /api/v1/interactions/{id} session Saved interactions
GET /api/v1/favorites, PUT/DELETE /api/v1/services/{slug}/favorites session Favorites
GET /api/v1/profile session Own login, role and teams

Exports#

Method and path Access Purpose
POST /api/v1/exports session Start an export (needs the export feature)
GET /api/v1/exports, GET /api/v1/exports/{id} session, own History and one export
GET /api/v1/exports/{id}/download session, own The file
POST /api/v1/exports/delete session, own Delete exports
/api/v1/export-pages... session, own Cover page library

Administration#

Method and path Access Purpose
/api/v1/admin/users... admin Users, two-factor reset, forced unlink
/api/v1/admin/services... admin Services and token rotation
/api/v1/admin/service-groups... admin Service groups
/api/v1/admin/teams... admin Teams
/api/v1/admin/sso/... admin SSO providers and settings
/api/v1/admin/notifications/... admin Channels, SMTP, rules, deliveries
/api/v1/admin/mcp-tokens... admin MCP tokens
GET/PUT /api/v1/services/{slug}/mcp-tryit admin Endpoints allowed for MCP Try-It
POST /api/v1/admin/license admin Upload a license
POST /api/v1/admin/rebuild admin Rebuild merged documents

MCP and SSO#

Method and path Access Purpose
/mcp MCP token The MCP endpoint. See MCP Server
GET /auth/sso/{slug}/login, .../callback, POST /auth/sso/exchange public The SSO sign-in flow

Errors#

Errors are JSON with an error message. Common statuses: 400 invalid input, 401 no valid session, 402 no valid license or a license limit (code: "license_limit"), 403 not allowed, 404 not found, 409 conflict (someone saved in between, or deleting the current version), 429 a quota is spent.

Next steps#

Last updated: