> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# 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

```text
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:

```text
Authorization: Bearer <access_token>
```

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](/en/api/authentication.md). External programs can call experts through [Agent MCP](/en/api/agent-mcp.md).

## Interactive API docs

Octop ships the [Scalar](https://scalar.com/) 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

| 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

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

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**](/en/api/authentication.md)

Log in with password, LDAP, OIDC, OAuth SSO, or an invite.

[**Users and admin**](/en/api/users-admin.md)

Create accounts, roles, invites, and directory login.

[**Agents**](/en/api/agents.md)

Create, share, and run experts.

[**Agent MCP**](/en/api/agent-mcp.md)

Let external MCP clients call your experts.

[**Chat**](/en/api/chat.md)

Stream turns and manage threads.

[**Knowledge**](/en/api/knowledge.md)

Create knowledge bases and upload documents.
