# MyOpenClaw.cloud Developer API v1 — Full Reference > Programmatic API for managing managed OpenClaw personal AI assistant instances. > Available to Pro ($49/mo) and Business ($99/mo) plan subscribers. Base URL: https://www.myopenclaw.cloud/api/v1 --- ## Authentication All requests require a Bearer token in the Authorization header: Authorization: Bearer moc__ API keys are created from the Dashboard (/dashboard/api) or via POST /api/v1/keys. Key format: moc__ - moc_ — fixed prefix - shortToken — used for DB lookup (not secret) - longToken — HMAC-SHA256 hashed server-side, never stored in plaintext The full key is shown only once at creation. Store it securely. Cookie-bearing requests are rejected (confused-deputy prevention). Do not send browser cookies. --- ## Scopes Each API key has scopes controlling access: instance:read — Read instance status instance:write — Start, stop, restart instances provider:read — Read provider/model configuration provider:write — Update provider/model configuration integrations:read — Read integration settings integrations:write — Update integration settings agents:read — Read agent configurations agents:write — Update agent configurations operations:read — Poll async operation status keys:read — List and view API keys keys:write — Create and revoke API keys Shortcuts: "read" → all :read scopes "write" → all scopes "all" → all scopes --- ## Rate Limits Per-key limits (requests per minute): | Operation | Pro | Business | |-----------|--------|----------| | Read | 120/m | 240/m | | Write | 30/m | 60/m | | Heavy | 5/m | 10/m | Global ceiling (per user, all keys combined): Pro: 1,000/min Business: 2,000/min Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset Rate limited: 429 with Retry-After header Redis unavailable: 503 Service Unavailable (fail-closed) --- ## Common Headers Request: Authorization: Bearer moc_xxx_yyy (required) Content-Type: application/json (for POST/PUT) Idempotency-Key: (optional, for start/restart) Response: X-Request-Id: req_... (unique request ID) X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset Location: /api/v1/operations/:id (for 202 responses) Retry-After: (for 429, 503, and pending operations) --- ## Error Format All errors: { "error": "Human-readable message", "code": "ERROR_CODE" } Validation errors also include "param" field. Error codes: 400 VALIDATION_ERROR — Invalid input (check param field) 400 NOT_PROVISIONED — Instance not fully provisioned 400 CANNOT_REVOKE_SELF — Key cannot revoke itself 401 INVALID_API_KEY — Missing, invalid, revoked, or expired key 402 PAYMENT_REQUIRED — Subscription needed 403 PLAN_REQUIRED — Requires Pro or Business plan 403 INSUFFICIENT_SCOPE — Key lacks required scope 403 SCOPE_ESCALATION — Cannot create key with broader scopes 404 NOT_FOUND — Resource not found 409 ALREADY_RUNNING — Instance already running 409 ALREADY_STOPPED — Instance already stopped 409 NOT_RUNNING — Instance must be running 422 KEY_LIMIT_REACHED — Max API keys reached 429 RATE_LIMITED — Too many requests 500 INTERNAL_ERROR — Server error 503 SERVICE_UNAVAILABLE — Temporary outage --- ## Endpoints ### GET /api/v1/instances/:instanceId Get instance status. Scope: instance:read Rate limit: read Path: instanceId — UUID or username Response 200: { "id": "uuid", "username": "alice", "subdomain": "alice.myopenclaw.cloud", "domain": "alice.myopenclaw.cloud", "status": "running", "plan": "pro", "fly_region": "dfw", "openclaw_version": "2026.2.26", "created_at": "2026-02-01T00:00:00.000Z", "updated_at": "2026-02-28T12:00:00.000Z" } Instance statuses: provisioning, pending_payment, running, paused_payment_failed, paused_subscription_ended, stopped, failed --- ### POST /api/v1/instances/:instanceId/start Start a stopped instance (async). Scope: instance:write Rate limit: heavy Path: instanceId — UUID or username Headers: Idempotency-Key (optional) Response 202: { "operation": { "id": "op_abc123def456", "type": "instance.start", "status": "pending", "created_at": "2026-03-01T00:00:00.000Z" }, "links": { "poll": "/api/v1/operations/op_abc123def456" } } Headers: Location: /api/v1/operations/op_abc123def456, Retry-After: 5 Errors: 409 ALREADY_RUNNING — Instance already running 402 PAYMENT_REQUIRED — No active subscription 400 NOT_PROVISIONED — Instance not fully provisioned --- ### POST /api/v1/instances/:instanceId/stop Stop a running instance (synchronous). Scope: instance:write Rate limit: heavy Path: instanceId — UUID or username Response 200: { "id": "uuid", "status": "stopped", "domain": "alice.myopenclaw.cloud" } Errors: 409 ALREADY_STOPPED — Instance already stopped --- ### POST /api/v1/instances/:instanceId/restart Restart a running instance (async). Scope: instance:write Rate limit: heavy Path: instanceId — UUID or username Headers: Idempotency-Key (optional) Response 202: { "operation": { "id": "op_abc123def456", "type": "instance.restart", "status": "pending", "created_at": "2026-03-01T00:00:00.000Z" }, "links": { "poll": "/api/v1/operations/op_abc123def456" } } Errors: 409 NOT_RUNNING — Instance must be running --- ### GET /api/v1/operations/:operationId Poll a single async operation. Scope: operations:read Rate limit: read Response 200 (pending/running): { "id": "op_abc123def456", "type": "instance.start", "status": "running", "created_at": "2026-03-01T00:00:00.000Z" } Headers: Retry-After: 5 Response 200 (succeeded): { "id": "op_abc123def456", "type": "instance.start", "status": "succeeded", "result": { "success": true, "domain": "alice.myopenclaw.cloud", "version": "2026.2.26" }, "created_at": "2026-03-01T00:00:00.000Z", "completed_at": "2026-03-01T00:01:30.000Z" } Headers: Cache-Control: public, max-age=3600 Response 200 (failed): { "id": "op_abc123def456", "type": "instance.start", "status": "failed", "error": { "code": "FLY_API_ERROR", "message": "Failed to start machine" }, "created_at": "2026-03-01T00:00:00.000Z", "completed_at": "2026-03-01T00:00:45.000Z" } Headers: Cache-Control: public, max-age=3600 --- ### GET /api/v1/operations List async operations. Scope: operations:read Rate limit: read Query parameters: status — Filter: pending, running, succeeded, failed limit — 1-100 (default: 20) Response 200: { "operations": [ { "id": "op_abc123def456", "type": "instance.restart", "status": "succeeded", "created_at": "2026-03-01T00:00:00.000Z", "completed_at": "2026-03-01T00:01:30.000Z" } ], "has_more": false } --- ### POST /api/v1/keys Create a new API key. The full key is returned only once. Scope: keys:write Rate limit: write Request body: { "name": "CI/CD Pipeline", // string, 1-64 chars, required "scopes": ["instance:read", "instance:write"], // string[], required "expires_in_days": 90 // integer 1-365, optional } Scope escalation prevention: cannot create key with broader scopes than the creating key. Response 201: { "id": "key_abc123", "name": "CI/CD Pipeline", "key": "moc_abc123_longSecretToken", "short_token": "abc123", "scopes": ["instance:read", "instance:write"], "last_used_at": null, "created_at": "2026-03-01T00:00:00.000Z", "expires_at": "2026-05-30T00:00:00.000Z", "revoked_at": null } IMPORTANT: The "key" field is shown only once. Store it immediately. Errors: 400 VALIDATION_ERROR — Invalid name, scopes, or expires_in_days 403 SCOPE_ESCALATION — Broader scopes than creating key 422 KEY_LIMIT_REACHED — Maximum keys reached --- ### GET /api/v1/keys List all API keys. Does not include secret material. Scope: keys:read Rate limit: read Response 200: { "keys": [ { "id": "key_abc123", "name": "CI/CD Pipeline", "short_token": "abc123", "scopes": ["instance:read", "instance:write"], "last_used_at": "2026-03-01T10:00:00.000Z", "created_at": "2026-03-01T00:00:00.000Z", "expires_at": "2026-05-30T00:00:00.000Z", "revoked_at": null } ] } --- ### GET /api/v1/keys/:keyId Get a single API key. Scope: keys:read Rate limit: read Response 200: Same shape as a single item in the keys array above. --- ### DELETE /api/v1/keys/:keyId Revoke an API key. Immediate and permanent. Scope: keys:write Rate limit: write Constraint: A key cannot revoke itself (returns 400 CANNOT_REVOKE_SELF). Response 200: { "id": "key_abc123", "revoked_at": "2026-03-01T12:00:00.000Z" } --- ## Idempotency For start/restart, include Idempotency-Key header: Idempotency-Key: my-unique-key-123 If an operation exists with that key for your user, the existing operation is returned regardless of its status. --- ## Polling Pattern 1. Call start or restart — receive 202 with operation ID 2. Poll GET /api/v1/operations/:id every 5 seconds 3. Continue until status is "succeeded" or "failed" 4. Check result or error fields Example (curl): # Start curl -X POST -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/instances/alice/start # Poll (repeat until status is succeeded or failed) curl -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/operations/op_abc123def456 Example (Python): import time, requests resp = requests.post( "https://www.myopenclaw.cloud/api/v1/instances/alice/start", headers={"Authorization": "Bearer moc_xxx_yyy"} ) op = resp.json()["operation"] while op["status"] in ("pending", "running"): time.sleep(5) resp = requests.get( f"https://www.myopenclaw.cloud/api/v1/operations/{op['id']}", headers={"Authorization": "Bearer moc_xxx_yyy"} ) op = resp.json() if op["status"] == "succeeded": print("Started:", op["result"]["domain"]) else: print("Failed:", op["error"]["message"]) --- ## Quick Reference (curl) # Instance status curl -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/instances/alice # Stop curl -X POST -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/instances/alice/stop # Start (async) curl -X POST -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/instances/alice/start # Restart (async) curl -X POST -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/instances/alice/restart # Poll operation curl -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/operations/op_abc123 # List operations curl -H "Authorization: Bearer $KEY" \ "https://www.myopenclaw.cloud/api/v1/operations?status=succeeded&limit=10" # Create key curl -X POST -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"name":"My Key","scopes":["read"]}' \ https://www.myopenclaw.cloud/api/v1/keys # List keys curl -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/keys # Revoke key curl -X DELETE -H "Authorization: Bearer $KEY" \ https://www.myopenclaw.cloud/api/v1/keys/key_abc123