Skip to main content

​
Devices API

Manage device pairing for your agent. Devices start in a pending state and can be approved, denied, or revoked.

​
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

​
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,
  "device": {
    "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:35:00Z",
    "status": "approved"
  },
  "pending": [],
  "approved": [
    { ... }
  ]
}
FieldTypeDescription
successbooleantrue when the action was applied
deviceobjectThe updated device object
pendingarrayRemaining pending devices
approvedarrayCurrently approved devices

​
Errors

CodeDescription
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.raveculture.xyz/api/devices \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "dev_pending_1",
    "action": "approve"
  }'

​
Example: revoke a device

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