• English

      • 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

      MethodPathAuthDescription
      GET/agentsuserList all agents for current user
      POST/agentsuserCreate a new agent
      GET/agents/{id}ownerGet full agent details
      PATCH/agents/{id}ownerUpdate agent settings
      DELETE/agents/{id}ownerDelete agent and permanently remove its workspace
      POST/agents/{id}/startownerStart agent runtime
      POST/agents/{id}/stopownerStop agent runtime
      POST/agents/{id}/reloadownerReload agent (rebuild runtime)
      POST/agents/{id}/readownerClear unread badge
      GET/agents/{id}/statusownerGet runtime state
      POST/agents/from-expert/{expert_id}userCreate from expert template
      GET/agents/{id}/tool-settingsownerList builtin and plugin tool toggles
      PUT/agents/{id}/tool-settingsownerSet builtin denylist and plugin tool enables
      PATCH/agents/{id}/tool-settings/{tool_name}ownerToggle one tool
      POST/agents/{id}/publish-expertownerPublish a workspace snapshot as an installable expert

      List agents

      Retrieve all agents belonging to the authenticated user.

      cURL
      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
      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

      namestringbodyrequired

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

      persona_mbtistringbody

      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_modelstringbody

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

      system_promptstringbody

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

      descriptionstringbody

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

      template_namestringbody

      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.

      Start
      Stop
      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
      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.

      cURL
      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):

      MethodPathWhat it does
      POST/agents/{id}/skill-packages/{package_id}/copyCopy selected package skills into the workspace (skill_slugs, optional overwrite)
      POST/agents/{id}/skills/{slug}/push-to-packageCopy 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
      Get a specific profile
      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
      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"}'