Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt

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

​
Devices API

Manage device pairing for your agent. Devices can be self-paired (auto-approved) or created via a pairing code flow where they start in a pending state and can be approved, denied, or revoked.
All device endpoints require an authenticated session. Unauthenticated requests receive a 401 response.

​
List devices

GET /api/devices
Returns all pending and approved devices grouped by status.

​
Response

{
  "pending": [
    {
      "id": "dev_pending_1",
      "name": "iPhone 15 Pro — Atlas Mobile",
      "ip": "86.23.104.12",
      "firstSeen": "2026-03-27T14:22:00Z",
      "lastSeen": "2026-03-27T15:30:00Z",
      "status": "pending"
    }
  ],
  "approved": [
    {
      "id": "dev_approved_1",
      "name": "Docker Container — agentbot-prod",
      "ip": "10.0.1.42",
      "firstSeen": "2026-03-25T09:00:00Z",
      "lastSeen": "2026-03-27T15:29:00Z",
      "status": "approved"
    }
  ]
}
FieldTypeDescription
pendingarrayDevices awaiting approval
approvedarrayDevices that have been approved

​
Device object

FieldTypeDescription
idstringUnique device identifier
namestringHuman-readable device name
ipstringIP address of the device
firstSeenstringISO 8601 timestamp when the device was first detected
lastSeenstringISO 8601 timestamp of the device’s most recent activity
statusstringOne of pending, approved, denied, or revoked

​
Errors

CodeDescription
401Unauthorized — no authenticated session

​
Generate a pairing code

PUT /api/devices
Creates a new device in pending status and returns a pairing code. Use this when you want another device to complete the pairing flow via a code or URL.

​
Query parameters

ParameterTypeRequiredDefaultDescription
namestringNoMy DeviceHuman-readable name for the device

​
Response

{
  "success": true,
  "deviceId": "dev_abc123",
  "pairingCode": "X7K2M9",
  "pairingUrl": "/dashboard/devices?pair=X7K2M9&id=dev_abc123"
}
FieldTypeDescription
successbooleantrue when the pairing code was generated
deviceIdstringIdentifier of the newly created device
pairingCodestringSix-character alphanumeric code for pairing
pairingUrlstringURL path to complete the pairing in the dashboard

​
Example

curl -X PUT "https://agentbot.sh/api/devices?name=Living+Room+iPad"

​
Errors

CodeDescription
401Unauthorized — no authenticated session

​
Self-pair a device

POST /api/devices/pair
Pairs the current device directly with auto-approval. This is used for self-pairing flows such as the “Pair My iPhone” button, where the requesting device is the one being paired.

​
Request body

FieldTypeRequiredDefaultDescription
namestringNoMy iPhoneHuman-readable name for the device

​
Response

{
  "success": true,
  "device": {
    "id": "dev_xyz789",
    "name": "My iPhone",
    "status": "approved",
    "pairedAt": "2026-04-09T16:20:00Z"
  }
}
FieldTypeDescription
successbooleantrue when the device was paired
deviceobjectThe newly paired device
device.idstringUnique device identifier
device.namestringHuman-readable device name
device.statusstringAlways approved for self-paired devices
device.pairedAtstringISO 8601 timestamp of when the device was paired

​
Example

curl -X POST https://agentbot.sh/api/devices/pair \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My iPhone"
  }'

​
Errors

CodeDescription
401Unauthorized — no authenticated session

​
Manage a device

POST /api/devices
Approve, deny, or revoke a device. The action must be valid for the device’s current status:
  • approve — only valid when the device is pending
  • deny — only valid when the device is pending
  • revoke — only valid when the device is approved

​
Request body

FieldTypeRequiredDescription
deviceIdstringYesThe identifier of the device to act on
actionstringYesOne of approve, deny, or revoke

​
Response

{
  "success": true,
  "pending": [],
  "approved": [
    {
      "id": "dev_approved_1",
      "name": "iPhone 15 Pro — Atlas Mobile",
      "ip": "86.23.104.12",
      "firstSeen": "2026-03-27T14:22:00Z",
      "lastSeen": "2026-03-27T15:35:00Z",
      "status": "approved"
    }
  ]
}
FieldTypeDescription
successbooleantrue when the action was applied
pendingarrayRemaining pending devices
approvedarrayCurrently approved devices

​
Errors

CodeDescription
401Unauthorized — no authenticated session
400Missing required fields: deviceId, action — one or both required fields are missing
400Invalid action. Must be: approve, deny, or revoke — the action is not recognized
400Device is not pending — attempted to approve or deny a device that is not in pending status
400Device is not approved — attempted to revoke a device that is not in approved status
400Invalid request body — the request body is not valid JSON
404Device not found — no device exists with the given identifier

​
Example: approve a device

curl -X POST https://agentbot.sh/api/devices \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "dev_pending_1",
    "action": "approve"
  }'

​
Example: revoke a device

curl -X POST https://agentbot.sh/api/devices \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "dev_approved_1",
    "action": "revoke"
  }'

​
OpenClaw devices proxy (deprecated)

These proxy endpoints are deprecated and will be removed in a future release. Device management now uses the local endpoints documented above (/api/devices and /api/devices/pair) instead of proxying to the agent runtime.
The following endpoints previously proxied device management requests to the agent’s OpenClaw runtime. They have been replaced by the local device pairing API.

​
List paired devices (runtime)

GET /api/openclaw/devices
Returns the list of devices paired with the agent’s runtime. Proxies to the agent’s GET /api/devices endpoint.

​
Errors

CodeDescription
401Unauthorized — no authenticated session
404No agent deployed — the user has no running agent instance
502Agent unreachable — the agent instance did not respond within 10 seconds

​
Manage paired devices (runtime)

POST /api/openclaw/devices
Perform device actions on the agent’s runtime. The action field determines the behavior.

​
Request body

FieldTypeRequiredDescription
actionstringYesOne of pair, unpair, or test-push
deviceIdstringConditionalRequired for unpair and test-push actions

​
Actions

ActionDescriptionProxies to
pairGenerate a QR code for pairing a new devicePOST /api/devices/pair
unpairUnpair an existing devicePOST /api/devices/unpair
test-pushSend a test push notification to a paired devicePOST /api/devices/test-push

​
Example: pair a new device

curl -X POST https://agentbot.sh/api/openclaw/devices \
  -H "Content-Type: application/json" \
  -d '{
    "action": "pair"
  }'

​
Example: unpair a device

curl -X POST https://agentbot.sh/api/openclaw/devices \
  -H "Content-Type: application/json" \
  -d '{
    "action": "unpair",
    "deviceId": "device_abc123"
  }'

​
Example: test push notification

curl -X POST https://agentbot.sh/api/openclaw/devices \
  -H "Content-Type: application/json" \
  -d '{
    "action": "test-push",
    "deviceId": "device_abc123"
  }'

​
Errors

CodeDescription
400Invalid action — the action field is not pair, unpair, or test-push
400Invalid request body — the request body is not valid JSON
401Unauthorized — no authenticated session
404No agent deployed — the user has no running agent instance
502Agent unreachable — the agent instance did not respond within 15 seconds