Octop REST and WebSocket API: Endpoints and Access Guide
Octop exposes every feature through an HTTP and WebSocket API at /api. Most endpoints need a JWT from POST /api/auth/login. Responses are JSON unless the endpoint streams events or returns a file.
Base URL
Replace the host and port if you run Octop somewhere else.
Get a token
Post your username and password to POST /api/auth/login, then send the token on later requests:
The chat WebSocket takes the same token as ?token=<access_token>. You can also sign in with OIDC, Feishu / DingTalk / WeCom OAuth, LDAP (same login form), or an invite link — see Authentication. External programs can call experts through Agent MCP.
Interactive API docs
Octop ships the Scalar interface for trying endpoints in the browser. It is off by default.
Enable it
Set "enable_api_docs": true in ~/.octop/config.json, or set OCTOP_ENABLE_API_DOCS=1.
Restart Octop
Restart octop run.
Open the docs
Visit http://127.0.0.1:8088/api/docs. The raw schema is always at /api/openapi.json.
Who can call what
Administrators can do everything. Regular users only get extra settings access if you grant it.
Check that the server is up
Login attempts are rate-limited (default 5 tries, then a 15-minute lockout). An administrator can unlock an account from Management → Users.
Explore the API
Log in with password, LDAP, OIDC, OAuth SSO, or an invite.
Create accounts, roles, invites, and directory login.
Create, share, and run experts.
Let external MCP clients call your experts.
Stream turns and manage threads.
Create knowledge bases and upload documents.

