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.
On this page
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#