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.

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.

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

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.

Start

curl -X POST http://127.0.0.1:8088/api/agents/researcher/start \
  -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.

cURL

curl -X POST http://127.0.0.1:8088/api/agents/researcher/reload \
  -H 'Authorization: Bearer $TOKEN'

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.

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

​

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

List all MBTI codes

curl http://127.0.0.1:8088/api/mbti/codes \
  -H 'Authorization: Bearer $TOKEN'

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

cURL

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"}'