# OpenClaw as a Service API Reference

Use the same origin that served this document as the base host. Production is `https://openclaw-as-a-service.com`.

## Authentication

- Header: `Authorization: Bearer YOUR_API_KEY`
- Create keys: `/account`
- Discover runtime metadata: `GET /api`

## Resources

The API root advertises the main contract:

- `/api/instances`
- `/api/instances/{instanceId}`
- `/api/instances/{instanceId}/chat`
- `/api/instances/{instanceId}/chat/stream`
- `/api/instances/{instanceId}/chat/events`
- `/api/instances/{instanceId}/chat/messages`
- `/api/instances/{instanceId}/files`
- `/api/instances/{instanceId}/files/read`
- `/api/instances/{instanceId}/files/write`
- `/api/instances/{instanceId}/terminal/exec`
- `/api/instances/{instanceId}/terminal/ws`
- `/api/instances/{instanceId}/vnc/ws`

## Instance lifecycle

### List instances

```bash
curl -s https://openclaw-as-a-service.com/api/instances \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response shape:

```json
[
  {
    "id": "8b21f18f-20eb-44ce-a31a-06798aea3e50",
    "status": "ready",
    "sandbox_id": "sandy-aaaaaaaaaaaa",
    "created_at": "2026-03-20T18:22:54.000Z",
    "updated_at": "2026-03-20T18:23:59.000Z"
  }
]
```

### Create instance

Use this when the authenticated user has an active subscription or passes a valid invite code that can be redeemed.

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invite_code":"YOUR_INVITE_CODE_IF_NEEDED"}'
```

The server returns `201` with the new instance payload. If capacity is exhausted, expect `503`. If access is missing, expect `403`.

### Inspect one instance

```bash
curl -s https://openclaw-as-a-service.com/api/instances/INSTANCE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Lifecycle controls

- Reboot: `POST /api/instances/{instanceId}/reboot`
- Shutdown: `POST /api/instances/{instanceId}/shutdown`
- Status: `GET /api/instances/{instanceId}/status`
- Desktop URL helper: `GET /api/instances/{instanceId}/vnc-url`

## Chat

### Create or list sessions

```bash
curl -s https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"CLI session"}'
```

### Send a synchronous message

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"CHAT_SESSION_ID","message":"Inspect /workspace and summarize the repo."}'
```

Response includes the persisted user message and assistant message.

### Stream a message over SSE

```bash
curl -N -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"CHAT_SESSION_ID","message":"Continue from the last step."}'
```

Important SSE events:

- `status`
- `message`
- `complete`
- `system_notification`

### Read history

Latest N messages in chronological order:

```bash
curl -s "https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/messages?session_id=CHAT_SESSION_ID&tail=true&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Messages after a known message id:

```bash
curl -s "https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/messages?session_id=CHAT_SESSION_ID&after=MESSAGE_ID&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Follow persisted chat events

```bash
curl -N "https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/chat/events?session_id=CHAT_SESSION_ID&after=MESSAGE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This endpoint emits `ready` once and then `message` events whenever persisted chat messages change.

## Files

### List directory

```bash
curl -G https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/files \
  --data-urlencode "path=/workspace" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Read text file

```bash
curl -G https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/files/read \
  --data-urlencode "path=/workspace/README.md" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Write text file

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/files/write \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/workspace/notes.txt","content":"Hello from the API"}'
```

### Upload file content

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetDir":"/workspace","fileName":"hello.txt","content":"Hello from upload"}'
```

### Other file operations

- Make directory: `POST /api/instances/{instanceId}/files/mkdir`
- Rename: `POST /api/instances/{instanceId}/files/rename`
- Delete: `POST /api/instances/{instanceId}/files/delete`
- Download binary file: `GET /api/instances/{instanceId}/files/download?path=...`

## Terminal and computer control

### Execute one command

```bash
curl -X POST https://openclaw-as-a-service.com/api/instances/INSTANCE_ID/terminal/exec \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"pwd","timeout_ms":5000}'
```

Example response:

```json
{
  "command": "pwd",
  "stdout": "/workspace\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 112
}
```

### Terminal websocket

Upgrade:

`GET /api/instances/{instanceId}/terminal/ws`

Provide the bearer key as an `Authorization` header during the WebSocket handshake.

### Desktop websocket

First resolve the proxied VNC URL:

`GET /api/instances/{instanceId}/vnc-url`

Then connect:

`GET /api/instances/{instanceId}/vnc/ws`

## Agent bundle and skills

Published companion artifacts:

- Interactive docs: `/docs`
- OpenAPI JSON: `/api/openapi.json`
- OpenAPI YAML: `/api/openapi.yaml`
- Short agent brief: `/llms.txt`
- Extended agent brief: `/llms-full.md`
- Agent guide: `/agent.md`
- Reusable skill bundle: `/skills/openclaw-api-control/SKILL.md`
- Helper client: `/skills/openclaw-api-control/scripts/openclaw_api_client.mjs`

## Recommended agent bootstrap prompt

When handing this API to another agent, give it:

1. The API key
2. The docs URL
3. The API root URL
4. Optionally a preferred instance id

Example:

```text
Use my OpenClaw as a Service API.
Docs: https://openclaw-as-a-service.com/docs
API root: https://openclaw-as-a-service.com/api
API key: $OPENCLAW_API_KEY
Preferred instance: $OPENCLAW_INSTANCE_ID
```