API Reference

All requests go to the base URL https://api.orquestio.com. An interactive Swagger UI is available at /docs.

Authentication

Every endpoint except GET /health requires a Bearer token:

Authorization: Bearer <API_KEY>

Unauthenticated requests receive 401 Unauthorized.

Common error responses

Status	Meaning
`400`	State precondition not met (e.g. trying to stop an already-stopped instance)
`401`	Missing or invalid API key
`403`	Direct IP access — use the Cloudflare-fronted URL
`404`	Resource not found
`409`	Conflict — a concurrent operation is already running on this instance
`422`	Validation error in request body
`429`	Rate limit exceeded

Health

`GET /health`

Public endpoint. No authentication, no rate limit.

Response 200

{
  "status": "healthy",
  "checks": {
    "api": "ok",
    "database": "ok",
    "redis": "ok"
  }
}

Example

curl https://api.orquestio.com/health

Instances

`POST /instances/create`

Create a new tenant instance.


Auth	Required
Rate limit	10 req/min

Request body

Field	Type	Required	Validation	Default
`instance_id`	string	yes	`^[a-z0-9][a-z0-9-]*[a-z0-9]$`, 3–63 chars	—
`tenant_id`	string	yes	`^[a-z0-9][a-z0-9-]*[a-z0-9]$`, 3–63 chars	—
`blueprint_name`	string	no	`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`, max 63 chars	`"OpenClaw"`
`plan_id`	string	no	`^[a-z0-9][a-z0-9-]*[a-z0-9]$`, max 63 chars	`"openclaw-basic"`

Response 201

Returns the created instance record.

Example

curl -X POST https://api.orquestio.com/instances/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "acme-prod-01",
    "tenant_id": "acme-corp",
    "blueprint_name": "OpenClaw",
    "plan_id": "openclaw-basic"
  }'

`DELETE /instances/{instance_id}`

Destroy an instance and release all associated resources.


Auth	Required
Rate limit	10 req/min

Response 200

{
  "instance_id": "acme-prod-01",
  "state": "destroying"
}

Example

curl -X DELETE https://api.orquestio.com/instances/acme-prod-01 \
  -H "Authorization: Bearer $API_KEY"

`GET /instances/{instance_id}/status`

Return the full instance record.


Auth	Required
Rate limit	60 req/min

Response 200

{
  "instance_id": "acme-prod-01",
  "tenant_id": "acme-corp",
  "blueprint_name": "OpenClaw",
  "ec2_id": "i-0abc123def456789",
  "ip_address": "54.210.xx.xx",
  "state": "running",
  "access_url": "https://acme-prod-01.orquestio.com",
  "last_health_check": "2026-04-11T12:00:00Z",
  "created_at": "2026-04-10T08:30:00Z"
}

Example

curl https://api.orquestio.com/instances/acme-prod-01/status \
  -H "Authorization: Bearer $API_KEY"

`GET /instances/{instance_id}/health`

Proxy a health check to the running instance and return the result.


Auth	Required
Rate limit	60 req/min

Example

curl https://api.orquestio.com/instances/acme-prod-01/health \
  -H "Authorization: Bearer $API_KEY"

`POST /instances/{instance_id}/stop`

Stop the instance EC2. Requires the instance to be in running state.


Auth	Required
Rate limit	20 req/min

Example

curl -X POST https://api.orquestio.com/instances/acme-prod-01/stop \
  -H "Authorization: Bearer $API_KEY"

`POST /instances/{instance_id}/start`

Start a stopped instance. Requires the instance to be in stopped state.


Auth	Required
Rate limit	20 req/min

Example

curl -X POST https://api.orquestio.com/instances/acme-prod-01/start \
  -H "Authorization: Bearer $API_KEY"

`POST /instances/{instance_id}/restart`

Stop and start the instance. Requires the instance to be in running state.


Auth	Required
Rate limit	20 req/min

Example

curl -X POST https://api.orquestio.com/instances/acme-prod-01/restart \
  -H "Authorization: Bearer $API_KEY"

`PUT /instances/{instance_id}/resize`

Change the EC2 instance type.


Auth	Required
Rate limit	10 req/min

Request body

Field	Type	Required
`new_instance_type`	string	yes

Example

curl -X PUT https://api.orquestio.com/instances/acme-prod-01/resize \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_instance_type": "t3.large"}'

Custom Domain

Bring your own domain to an instance. The orchestrator provisions a Let’s Encrypt TLS certificate automatically.

`POST /instances/{instance_id}/custom-domain`

Attach a custom domain to the instance.


Auth	Required
Rate limit	10 req/min

Request body

Field	Type	Required
`domain`	string	yes

Response 202

The domain attachment is asynchronous. Poll the GET endpoint to track provisioning status.

Example

curl -X POST https://api.orquestio.com/instances/acme-prod-01/custom-domain \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.acme.com"}'

`GET /instances/{instance_id}/custom-domain`

Check the provisioning status of the custom domain.


Auth	Required
Rate limit	30 req/min

Example

curl https://api.orquestio.com/instances/acme-prod-01/custom-domain \
  -H "Authorization: Bearer $API_KEY"

`DELETE /instances/{instance_id}/custom-domain`

Remove the custom domain and its TLS certificate.


Auth	Required
Rate limit	10 req/min

Response 202

Removal is asynchronous.

Example

curl -X DELETE https://api.orquestio.com/instances/acme-prod-01/custom-domain \
  -H "Authorization: Bearer $API_KEY"

Control Plane Tasks

Dispatch arbitrary operations to an instance via SSM. Only one task can run per instance at a time — concurrent requests return 409.

`POST /instances/{instance_id}/tasks`

Dispatch a task.


Auth	Required
Rate limit	10 req/min
Concurrency	1 per instance

Request body

Field	Type	Required	Description
`operation_code`	string	yes	Identifier for the operation type
`script_path`	string	yes	Path to the script on the instance
`script_args`	object	no	Arguments passed to the script
`timeout_seconds`	integer	no	Max execution time
`idempotency_key`	string	no	Prevents duplicate execution of the same task

Response 202

The task is queued for execution. Use the task endpoints to poll for completion.

Example

curl -X POST https://api.orquestio.com/instances/acme-prod-01/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_code": "backup_db",
    "script_path": "/opt/openclaw/scripts/backup.sh",
    "script_args": {"compress": true},
    "timeout_seconds": 300,
    "idempotency_key": "backup-2026-04-11"
  }'

`GET /instances/{instance_id}/tasks`

List tasks for an instance. Supports pagination and filtering.


Auth	Required
Rate limit	60 req/min

Query parameters

Param	Type	Description
`status`	string	Filter by task status
`operation_code`	string	Filter by operation code
`limit`	integer	Page size
`offset`	integer	Pagination offset

Example

curl "https://api.orquestio.com/instances/acme-prod-01/tasks?status=completed&limit=10" \
  -H "Authorization: Bearer $API_KEY"

`GET /tasks/{task_id}`

Get details for a single task.


Auth	Required
Rate limit	60 req/min

Example

curl https://api.orquestio.com/tasks/task-abc123 \
  -H "Authorization: Bearer $API_KEY"