Octop REST and WebSocket API: Endpoints and Access Guide

Octop exposes a REST API and WebSocket chat endpoint at /api. Enable interactive docs at /api/docs when you want to try calls in the browser.

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

http://127.0.0.1:8088/api

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:

Authorization: Bearer <access_token>

The chat WebSocket takes the same token as ?token=<access_token>. You can also sign in with OIDC or an invite link — see Authentication.

​

Interactive API docs

Octop ships the Scalar interface for trying endpoints in the browser. It is off by default.

1. Enable it

   Set "enable_api_docs": true in ~/.octop/config.json, or set OCTOP_ENABLE_API_DOCS=1.

2. Restart Octop

   Restart octop run.

3. 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

Level	Meaning
public	No token required (health, login, first-run setup, OAuth callbacks)
user	Any signed-in account
owner	The person who owns the resource, or an administrator
admin	Administrator only

Administrators can do everything. Regular users only get extra settings access if you grant it.

​

Check that the server is up

curl http://127.0.0.1:8088/api/health
# {"status": "ok", "version": "0.9.28"}

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

Authentication

Log in, renew tokens, and sign in with OIDC or an invite.

Users and admin

Create accounts, send invites, and read audit data.

Agents

Create, share, and run agents.

Chat

Stream turns and manage threads.

Knowledge

Create knowledge bases and upload documents.