> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
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 theme={null}
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](https://octop.mintlify.site/api/authentication.md).

## Interactive API docs

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

```bash theme={null}
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

> [card] [Authentication](https://octop.mintlify.site/api/authentication.md)
>
> Log in, renew tokens, and sign in with OIDC or an invite.

> [card] [Users and admin](https://octop.mintlify.site/api/users-admin.md)
>
> Create accounts, send invites, and read audit data.

> [card] [Agents](https://octop.mintlify.site/api/agents.md)
>
> Create, share, and run agents.

> [card] [Chat](https://octop.mintlify.site/api/chat.md)
>
> Stream turns and manage threads.

> [card] [Knowledge](https://octop.mintlify.site/api/knowledge.md)
>
> Create knowledge bases and upload documents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.