# 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](/documentation/teams). 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](/documentation/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

- [Publishing a Specification](/documentation/publishing-specifications)
- [Roles and Permissions](/documentation/roles-and-permissions)

---
Source: https://selfdochub.com/documentation/api-reference
