Skip to main content
POST
/
devices
/
{id}
/
commands
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/commands \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "start_recording",
    "params": {
      "max_duration_sec": 3600,
      "upload_immediately": true,
      "metadata": {
        "session_id": "meeting-123"
      }
    }
  }'

{
  "id": "cmd_xyz789",
  "device_id": "dev_abc123",
  "type": "start_recording",
  "status": "pending",
  "params": {
    "max_duration_sec": 3600,
    "upload_immediately": true,
    "metadata": {
      "session_id": "meeting-123"
    }
  },
  "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "result": null,
  "error": null,
  "expires_at": "2025-01-20T11:00:00Z",
  "delivered_at": null,
  "executed_at": null,
  "created_at": "2025-01-20T10:55:00Z"
}
Send a remote command to a device. Commands are delivered via BLE (through the mobile app) or via heartbeat response (for 4G/WiFi devices).

​
Authentication

Requires an API key with devices:write scope. 
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/commands \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "start_recording",
    "params": {
      "max_duration_sec": 3600,
      "upload_immediately": true,
      "metadata": {
        "session_id": "meeting-123"
      }
    }
  }'

​
Path Parameters

​
id
string
required
The device’s unique identifier (e.g., dev_abc123).

​
Request Body

​
type
string
required
The command type. One of:
  • start_recording - Start a new recording
  • stop_recording - Stop the current recording
​
params
object
Optional parameters for the command.
​
params.max_duration_sec
number
Maximum recording duration in seconds (1-86400). Default: 3600 (1 hour).
​
params.upload_immediately
boolean
Whether to upload immediately after recording stops. Default: true.
​
params.metadata
object
Custom metadata to attach to the recording.
​
idempotency_key
string
Unique key to prevent duplicate command creation.
​
ttl_seconds
number
Time-to-live for the command in seconds. Command expires if not executed within this time. Default: 300 (5 minutes).

​
Response

Returns the command object with status set to pending. 
{
  "id": "cmd_xyz789",
  "device_id": "dev_abc123",
  "type": "start_recording",
  "status": "pending",
  "params": {
    "max_duration_sec": 3600,
    "upload_immediately": true,
    "metadata": {
      "session_id": "meeting-123"
    }
  },
  "grant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "result": null,
  "error": null,
  "expires_at": "2025-01-20T11:00:00Z",
  "delivered_at": null,
  "executed_at": null,
  "created_at": "2025-01-20T10:55:00Z"
}

​
Response Fields

FieldTypeDescription
idstringCommand identifier
device_idstringTarget device (dev_*)
typestringstart_recording or stop_recording
statusstringCommand status (see Command Lifecycle below)
paramsobjectCommand parameters
grant_tokenstringSigned authorization token for the device
resultobject | nullExecution result (populated after execution)
errorobject | nullError details (if failed)
expires_atstring | nullExpiration timestamp (ISO 8601)
delivered_atstring | nullWhen delivered to device (ISO 8601)
executed_atstring | nullWhen executed on device (ISO 8601)
created_atstringCreation timestamp (ISO 8601)

​
Command Lifecycle

Commands go through the following states:
StatusDescription
pendingCommand created, waiting to be delivered to device
deliveredCommand received by device, execution in progress
executedCommand successfully executed
failedCommand execution failed
expiredCommand expired before delivery
cancelledCommand was cancelled via API

​
Notes

  • Commands are delivered to devices via BLE (through the mobile app) or WiFi/4G (direct push)
  • If the device is offline, commands will be queued and delivered when the device comes online
  • The grant_token is a signed JWT that authorizes the device to execute the command
  • For BLE-connected devices, the mobile app must relay the command to the device