Skip to main content
PATCH
/
api
/
v1
/
agents
/
{agent_id}
Update Agent
curl --request PATCH \
  --url https://api.example.com/api/v1/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "board_id": "<string>",
  "is_gateway_main": true,
  "status": "<string>",
  "heartbeat_config": {},
  "identity_profile": {},
  "identity_template": "<string>",
  "soul_template": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JorgeMedinaArauna/OpenClaw-Mission_control/llms.txt

Use this file to discover all available pages before exploring further.

Updates an existing agent’s configuration. Changes to templates or configuration can trigger reprovisioning on the gateway.

​
Authentication

Requires organization admin authentication via Authorization: Bearer <token> header.

​
Path Parameters

​
agent_id
string
required
Agent UUID or ID to update

​
Query Parameters

​
force
boolean
default:"false"
Force reprovisioning even if no significant changes detected

​
Request Body

All fields are optional. Only include fields you want to update.
​
name
string
New display name for the agent
​
board_id
UUID
Move agent to a different board (requires appropriate permissions)
​
is_gateway_main
boolean
Designate this agent as the gateway main agent
​
status
string
Update lifecycle status: active, paused, retired
​
heartbeat_config
object
Update heartbeat policy
{
  "interval_seconds": 45
}
​
identity_profile
object
Update identity profile values
{
  "role": "coordinator",
  "skill": "escalation"
}
​
identity_template
string
Replace identity template (triggers reprovisioning)Example: “Focus on root cause analysis first.”
​
soul_template
string
Replace soul template (triggers reprovisioning)Example: “Escalate only after checking all known mitigations.”

​
Response

Returns an updated AgentRead object with the same structure as List Agents.

​
Reprovisioning Triggers

Updating these fields will trigger reprovisioning:
  • identity_template
  • soul_template
  • board_id (if moving to a different board)
Reprovisioning writes updated configuration files to the agent’s workspace on the gateway.

​
Example Request

curl -X PATCH "https://api.example.com/api/v1/agents/c91361ef-6d85-439c-82e1-8f388a302e6a" \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "identity_profile": {
      "role": "coordinator",
      "on_leave": true
    }
  }'

​
Example Response

{
  "id": "c91361ef-6d85-439c-82e1-8f388a302e6a",
  "gateway_id": "55cc268a-4b45-400f-accf-201e025232ac",
  "board_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Financial Operations Lead",
  "status": "paused",
  "gateway_agent_id": "agent-01JCXYZ123",
  "workspace_path": "/home/ubuntu/.openclaw/workspace-mc-c91361ef-6d85-439c-82e1-8f388a302e6a",
  "is_mc_agent": true,
  "is_board_lead": false,
  "is_gateway_main": false,
  "openclaw_session_id": "agent:mc-c91361ef-6d85-439c-82e1-8f388a302e6a:main",
  "last_seen_at": "2026-03-05T10:30:00Z",
  "created_at": "2026-03-01T08:00:00Z",
  "updated_at": "2026-03-05T11:15:00Z",
  "identity_profile": {
    "role": "coordinator",
    "on_leave": true
  }
}

​
Error Responses

​
403 Forbidden
Insufficient permissions to update this agent
​
404 Not Found
Agent ID does not exist or is not accessible
​
422 Unprocessable Entity
Validation failed (e.g., invalid status value)
​
502 Bad Gateway
Gateway RPC call failed during reprovisioning

​
Use Cases

  • Pause Agent: Set status: "paused" to temporarily disable an agent
  • Update Instructions: Change templates to adjust agent behavior
  • Move Agent: Reassign agent to a different board
  • Update Profile: Add metadata for routing decisions

Build docs developers (and LLMs) love

Get started for freeTalk to us