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

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
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
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, body, required)

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


- `persona_mbti` (string, body)

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, body)

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, body)

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, body)

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


- `template_name` (string, body)

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
curl -X POST http://127.0.0.1:8088/api/agents/researcher/start \
  -H 'Authorization: Bearer $TOKEN'
```
```bash Stop
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
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
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                                  |

`POST /skill-packages` and `PUT /skill-packages/{id}` accept `shared`. When it is `true`, other signed-in users can view and mount the package. Only the creator can edit or delete it. `visibility` and `group_ids` can narrow that further.

## 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/types` 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/types/{code}`.


```bash List all MBTI codes
curl http://127.0.0.1:8088/api/mbti/types \
  -H 'Authorization: Bearer $TOKEN'
```
```bash Get a specific profile
curl http://127.0.0.1:8088/api/mbti/types/INTJ \
  -H 'Authorization: Bearer $TOKEN'
```


You can also apply a persona to an existing agent and reload it with `POST /api/mbti/apply`. Pass the agent id in the `X-Octop-Agent-Id` header:


```bash cURL
curl -X POST http://127.0.0.1:8088/api/mbti/apply \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'X-Octop-Agent-Id: researcher' \
  -H 'Content-Type: application/json' \
  -d '{"code": "ENFP"}'
```

