API by router
Instances
GET
HTTPBearerheader
AuthorizationBearer <token>X-Api-Key?string|nullSuccessful Response
application/json- response
instances*array<>curl -X GET 'https://example.com/v1/instances'Example Response
{ "instances": [ { "agent_name": "string", "created_at": "2019-08-24T14:15:22Z", "customer_email": "string", "hostname": "string", "id": "string", "ip_address": "string", "preset_id": "string", "product_tier_name": "string", "provider": "string", "region_id": "string", "runtime_type": "expressclaw", "status": "string", "workload_type": "agent" } ]}POST
HTTPBearerheader
AuthorizationBearer <token>X-Api-Key?string|nullapplication/json- body
agent_name?|nullcustomer_id?|nullidempotency_key?|nullmanifest_id?|nullpreset_id?Preset IdDefault
"personal_assistant"recipe_id?|nullregion_id*Region Idtier_id*Tier Iduser_display_name?|nullwebsite_template_slug?|nullworkflow_slugs?array<string>|nullSuccessful Response
application/json- response
idempotency_key*Idempotency Keyinstance_id?string|nullmessage*Messagetask_id*Task Idcurl -X POST 'https://example.com/v1/instances' \ -H 'Content-Type: application/json' \ -d '{ "region_id": "string", "tier_id": "string"}'Example Response
{ "idempotency_key": "string", "instance_id": "string", "message": "string", "task_id": "string"}POST
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
instance_id*Instance Idstatus*Statuscurl -X POST 'https://example.com/v1/instances/admin/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate-key'Example Response
{ "instance_id": "string", "status": "string"}GET
HTTPBearerheader
AuthorizationBearer <token>idempotency_key*Idempotency KeyX-Api-Key?string|nullSuccessful Response
application/json- response
Lightweight response for polling deploy status by idempotency key.
Note: ip_address deliberately omitted — no need to expose VPS IP during the deploy flow. Operators can see it on the instance detail page. "Loose lips sink ships." — WWII poster (and provision poll responses)
bootstrap_seq?integer|nullbootstrap_stage?string|nullerror_message?string|nullfound*Foundhostname?string|nullinstance_id?string|nulllogs?array<>|nullprovisioning_stage?string|nullstatus?string|nullcurl -X GET 'https://example.com/v1/instances/by-key/string'Example Response
{ "bootstrap_seq": 0, "bootstrap_stage": "string", "error_message": "string", "found": true, "hostname": "string", "instance_id": "string", "logs": [ {} ], "provisioning_stage": "string", "status": "string"}POST
HTTPBearerheader
AuthorizationBearer <token>X-Api-Key?string|nullSuccessful Response
application/json- response
cleaned*Cleanederrors*Errorsmessage*Messagecurl -X POST 'https://example.com/v1/instances/cleanup'Example Response
{ "cleaned": 0, "errors": 0, "message": "string"}GET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
agent_name?string|nullcallback_seq?integer|nullcallback_stage?string|nullcapabilities?created_at*Created AtFormat
date-timeerror_message*string|nullhealth_status*Health Statushostname*Hostnameid*Idip_address*string|nullpreset_id?string|nullprovider*Providerprovisioning_stage*string|nullregion_id*string|nullruntime_type?Runtime TypeDefault
"expressclaw"server_type_plan*string|nullstatus*Statusupdated_at*Updated AtFormat
date-timevpn_ip*string|nullworkload_type?Workload TypeDefault
"agent"curl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08'Example Response
{ "agent_name": "string", "callback_seq": 0, "callback_stage": "string", "capabilities": { "property1": true, "property2": true }, "created_at": "2019-08-24T14:15:22Z", "error_message": "string", "health_status": "string", "hostname": "string", "id": "string", "ip_address": "string", "preset_id": "string", "provider": "string", "provisioning_stage": "string", "region_id": "string", "runtime_type": "expressclaw", "server_type_plan": "string", "status": "string", "updated_at": "2019-08-24T14:15:22Z", "vpn_ip": "string", "workload_type": "agent"}DELETE
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
already_deleted?Already DeletedDefault
falseinstance_id*Instance Idmessage*Messagestatus*Statuscurl -X DELETE 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08'Example Response
{ "already_deleted": false, "instance_id": "string", "message": "string", "status": "string"}POST
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
conversation_id?|nullmessage*MessageLength
1 <= length <= 8000Successful Response
response?unknownapplication/jsoncurl -X POST 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/chat' \ -H 'Content-Type: application/json' \ -d '{ "message": "string"}'Example Response
nullGET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
response?unknownapplication/jsoncurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/config'Example Response
nullPOST
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
agent_name?string|nullcustomer_facing_prompt?string|nullmodel_temperature?|nullrecipe_id?string|nullsystem_prompt?string|nulltelegram_bot_token?string|nullworkflow_slugs?array<string>|nullSuccessful Response
response?unknownapplication/jsoncurl -X POST 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/config' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
nullPATCH
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
consent_debug_access*Consent Debug AccessSuccessful Response
application/json- response
consent_debug_access*Consent Debug Accessinstance_id*Instance Idmessage*Messagecurl -X PATCH 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/consent' \ -H 'Content-Type: application/json' \ -d '{ "consent_debug_access": true}'Example Response
{ "consent_debug_access": true, "instance_id": "string", "message": "string"}GET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidlimit?LimitRange
1 <= value <= 100Default
20X-Api-Key?string|nullSuccessful Response
response?unknownapplication/jsoncurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations'Example Response
nullGET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidconversation_id*Conversation IdMatch
^[A-Za-z0-9:_-]{1,128}$Length
length <= 128X-Api-Key?string|nullSuccessful Response
response?unknownapplication/jsoncurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations/string'Example Response
nullGET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
Provision logs for an instance.
instance_id*Instance Idlogs*array<>total*Totalcurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/logs'Example Response
{ "instance_id": "string", "logs": [ { "created_at": "2019-08-24T14:15:22Z", "level": "string", "message": "string", "seq": 0, "stage": "string" } ], "total": 0}PATCH
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
Update the model policy for an instance.
budget_daily_usd?|nullbudget_monthly_usd?|nullembedding_model?string|nullfallbacks?array<string>|nullmax_tokens?|nullprimary?|nulltemperature?|nullSuccessful Response
application/json- response
instance_id*Instance Idmessage*Messagemodel_policy*curl -X PATCH 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/model-policy' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
{ "instance_id": "string", "message": "string", "model_policy": {}}GET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
Platform-level config stored in agent_config JSONB.
advanced?Default
{}channels?Default
{}instance_id*Instance Idintegrations?array<string>Default
[]recipe_id?string|nullskills?array<string>Default
[]workflow_slugs?array<string>Default
[]curl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/platform-config'Example Response
{ "advanced": {}, "channels": {}, "instance_id": "string", "integrations": [], "recipe_id": "string", "skills": [], "workflow_slugs": []}PATCH
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
Partial update — only provided fields are merged.
advanced?|nullchannels?|nullintegrations?array<string>|nullrecipe_id?string|nullskills?array<string>|nullworkflow_slugs?array<string>|nullSuccessful Response
application/json- response
Platform-level config stored in agent_config JSONB.
advanced?Default
{}channels?Default
{}instance_id*Instance Idintegrations?array<string>Default
[]recipe_id?string|nullskills?array<string>Default
[]workflow_slugs?array<string>Default
[]curl -X PATCH 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/platform-config' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
{ "advanced": {}, "channels": {}, "instance_id": "string", "integrations": [], "recipe_id": "string", "skills": [], "workflow_slugs": []}GET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullSuccessful Response
application/json- response
Runtime health and version info from the VPS agent.
Returns useful context in ALL states — not just when running. During provisioning: bootstrap_stage, provision_logs, health_status. When running: live agent data + health context. When unreachable: last known health data so the UI can explain WHY.
"I see dead processes." — Cole Sear, The Sixth Sense (networking edition)
active_connections?Active ConnectionsDefault
0bootstrap_seq?integer|nullbootstrap_stage?string|nullerror_code?string|nullerror_message?string|nullhealth_failures?Health FailuresDefault
0health_status?string|nullinstance_id*Instance Idlast_heartbeat?|nullnode_version?string|nullopenclaw_version?string|nullprovision_logs?array<>|nullprovisioning_stage?string|nullskills_loaded?array<string>Default
[]status*Statusuptime_seconds?integer|nullcurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/runtime'Example Response
{ "active_connections": 0, "bootstrap_seq": 0, "bootstrap_stage": "string", "error_code": "string", "error_message": "string", "health_failures": 0, "health_status": "string", "instance_id": "string", "last_heartbeat": "2019-08-24T14:15:22Z", "node_version": "string", "openclaw_version": "string", "provision_logs": [ {} ], "provisioning_stage": "string", "skills_loaded": [], "status": "string", "uptime_seconds": 0}POST
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuidX-Api-Key?string|nullapplication/json- body
Request to apply pending updates to a running instance.
force?ForceDefault
falserestart_agent?Restart AgentDefault
falseSuccessful Response
application/json- response
instance_id*Instance Idmessage*Messagestatus*Statuscurl -X POST 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/updates/apply' \ -H 'Content-Type: application/json' \ -d '{}'Example Response
{ "instance_id": "string", "message": "string", "status": "string"}GET
HTTPBearerheader
AuthorizationBearer <token>instance_id*Instance IdFormat
uuiddays?DaysDefault
30X-Api-Key?string|nullSuccessful Response
application/json- response
Usage metrics for a single instance.
daily*array<>hostname*Hostnameinstance_id*Instance Idtotal_cost_usd*Total Cost Usdtotal_requests*Total Requeststotal_tokens*Total Tokensunique_end_users*Unique End Userscurl -X GET 'https://example.com/v1/instances/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage'Example Response
{ "daily": [ {} ], "hostname": "string", "instance_id": "string", "total_cost_usd": "string", "total_requests": 0, "total_tokens": 0, "unique_end_users": 0}