> ## 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 Agents API: Create, Configure, and Control Agents

> REST endpoints for creating, configuring, and controlling Octop agents. Start, stop, reload, and read agent status via the HTTP API.

The Agents API lets you create and manage agents programmatically. Use these endpoints to spin up new agents, update their configuration, and control their runtime lifecycle. All endpoints require a Bearer token obtained from `POST /api/auth/login`.

## Base path

```
/api/agents
```

## Endpoints

| Method | Path | Auth | Description |
| - | - | - | - |
| `GET` | `/agents` | user | List all agents for current user |
| `POST` | `/agents` | user | Create a new agent |
| `GET` | `/agents/{id}` | owner | Get full agent details |
| `PATCH` | `/agents/{id}` | owner | Update agent settings |
| `DELETE` | `/agents/{id}` | owner | Delete agent and permanently remove its workspace |
| `POST` | `/agents/{id}/start` | owner | Start agent runtime |
| `POST` | `/agents/{id}/stop` | owner | Stop agent runtime |
| `POST` | `/agents/{id}/reload` | owner | Reload agent (rebuild runtime) |
| `POST` | `/agents/{id}/read` | owner | Clear unread badge |
| `GET` | `/agents/{id}/status` | owner | Get runtime state |
| `POST` | `/agents/from-expert/{expert_id}` | user | Create from expert template |
| `GET` | `/agents/{id}/tool-settings` | owner | List builtin and plugin tool toggles |
| `PUT` | `/agents/{id}/tool-settings` | owner | Set builtin denylist and plugin tool enables |
| `PATCH` | `/agents/{id}/tool-settings/{tool_name}` | owner | Toggle one tool |
| `POST` | `/agents/{id}/publish-expert` | owner | Publish a workspace snapshot as an installable expert |

## List agents

Retrieve all agents belonging to the authenticated user.

```bash cURL theme={null}
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer $TOKEN'
```

## Create an agent

Send a `POST` request with a JSON body to create a new agent.

```bash cURL theme={null}
curl -X POST http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "researcher",
    "persona_mbti": "INTJ",
    "default_model": "openai:gpt-4o",
    "description": "Research assistant"
  }'
```

### Request body

**name** `string` *required*

The agent's display name. Must be unique within your account.

**persona\_mbti** `string`

MBTI personality code that shapes the agent's tone and reasoning style — for example `INTJ` or `ENFP`. Octop ships 16 built-in profiles plus a `_default`.

**default\_model** `string`

Model identifier the agent uses for LLM calls — for example `openai:gpt-4o`. Must reference an enabled provider visible to your account.

**system\_prompt** `string`

Custom system prompt text appended to the persona profile. Use this to add domain-specific instructions or constraints on top of the MBTI persona.

**description** `string`

A short human-readable description of what the agent does. Displayed in the agent list.

**template\_name** `string`

Name of a bundled expert template to base the new agent on. Alternatively, use `POST /agents/from-expert/{expert_id}` to create from the expert catalog by ID.

> [!WARNING]
>
> `DELETE /agents/{id}` also permanently removes `~/.octop/agents/<id>/`. Workspace cleanup failure does not block the database delete. Back up first if you need the files.

## Start and stop an agent

Use the `start` and `stop` sub-routes to control the agent's runtime process without deleting it.

```bash Start theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/researcher/start \
  -H 'Authorization: Bearer $TOKEN'
```

```bash Stop theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/researcher/stop \
  -H 'Authorization: Bearer $TOKEN'
```

Both endpoints return `204 No Content` on success. To verify the resulting state, call `GET /agents/{id}/status`, which returns `{state, last_error?, ...}`.

## Reload an agent

`POST /agents/{id}/reload` tears down the running harness runtime and rebuilds it from the current configuration. Use this after updating skills, environment variables, or the system prompt to apply changes without recreating the agent.

```bash cURL theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/researcher/reload \
  -H 'Authorization: Bearer $TOKEN'
```

> [!NOTE]
>
> If another operation is already in flight for the agent, the server returns `409 AGENT_BUSY`. Wait for the current operation to finish before reloading.

## Create from an expert template

Octop ships a catalog of pre-built expert agents. Use `POST /agents/from-expert/{expert_id}` to instantiate one with a custom name.

```bash cURL theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/from-expert/code-reviewer \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-code-reviewer"}'
```

Retrieve the expert catalog first with `GET /api/experts` to find valid `expert_id` values.

## Share an agent

When you create or update an agent, set `is_shared` to `true` so other people on this instance can open it. Only the owner can change it. `GET /agents` returns your agents plus shared ones. Administrators can pass `scope=all` to list every agent.

## Publish as an expert template

`POST /agents/{id}/publish-expert` copies the agent's workspace into a template other users can install from the expert market. Incoming uploads and secrets are left out. List and install published experts with `GET /api/experts/published` and `POST /api/experts/published/{expert_id}/install`.

## Per-agent tool toggles

`GET` and `PUT` `/agents/{id}/tool-settings` turn built-in and plugin tools on or off for one agent — the same controls as **Personalization**. Plugin changes take effect immediately. A few built-in tools always stay on (`ls`, `read_file`, `glob`, `grep`, `write_todos`, `task`).

Copy skills as snapshots (the source and destination do not stay in sync):

| Method | Path | What it does |
| - | - | - |
| `POST` | `/agents/{id}/skill-packages/{package_id}/copy` | Copy selected package skills into the workspace (`skill_slugs`, optional `overwrite`) |
| `POST` | `/agents/{id}/skills/{slug}/push-to-package` | Copy a workspace skill into a package you can modify |

## MBTI persona codes

When creating or updating an agent, you can set `persona_mbti` to any of the 16 built-in MBTI codes (or `_default`). Use `GET /api/mbti/codes` to retrieve the full list of available codes along with their display names and descriptions. To inspect the detailed profile for a specific code — including personality dimensions, behaviour mappings, and UI metadata — call `GET /api/mbti/codes/{code}`.

```bash List all MBTI codes theme={null}
curl http://127.0.0.1:8088/api/mbti/codes \
  -H 'Authorization: Bearer $TOKEN'
```

```bash Get a specific profile theme={null}
curl http://127.0.0.1:8088/api/mbti/codes/INTJ \
  -H 'Authorization: Bearer $TOKEN'
```

You can also apply a persona to an existing agent and immediately reload it with `PUT /api/agents/{id}/mbti`:

```bash cURL theme={null}
curl -X PUT http://127.0.0.1:8088/api/agents/researcher/mbti \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"code": "ENFP"}'
```


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