Reset Device

curl -X POST https://api.bota.dev/v1/devices/dev_abc123/reset \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch('https://api.bota.dev/v1/devices/dev_abc123/reset', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTA_API_KEY}`,
  },
});

const resetCommand = await response.json();

import os
import requests

response = requests.post(
    'https://api.bota.dev/v1/devices/dev_abc123/reset',
    headers={'Authorization': f'Bearer {os.environ["BOTA_API_KEY"]}'},
)

reset_command = response.json()

{
  "id": "cmd_xyz789",
  "device_id": "dev_abc123",
  "type": "factory_reset",
  "status": "pending",
  "params": {},
  "grant_token": "rct_...",
  "result": null,
  "error": null,
  "expires_at": null,
  "delivered_at": null,
  "executed_at": null,
  "created_at": "2026-07-26T08:00:00Z"
}

{
  "error": {
    "code": "resource_not_found",
    "message": "Device not found: dev_abc123"
  }
}

POST

devices

{id}

reset

curl -X POST https://api.bota.dev/v1/devices/dev_abc123/reset \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch('https://api.bota.dev/v1/devices/dev_abc123/reset', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTA_API_KEY}`,
  },
});

const resetCommand = await response.json();

import os
import requests

response = requests.post(
    'https://api.bota.dev/v1/devices/dev_abc123/reset',
    headers={'Authorization': f'Bearer {os.environ["BOTA_API_KEY"]}'},
)

reset_command = response.json()

{
  "id": "cmd_xyz789",
  "device_id": "dev_abc123",
  "type": "factory_reset",
  "status": "pending",
  "params": {},
  "grant_token": "rct_...",
  "result": null,
  "error": null,
  "expires_at": null,
  "delivered_at": null,
  "executed_at": null,
  "created_at": "2026-07-26T08:00:00Z"
}

{
  "error": {
    "code": "resource_not_found",
    "message": "Device not found: dev_abc123"
  }
}

Create a durable factory-reset command for a device. The request is asynchronous: 202 Accepted means the command is pending, not that the device has already been wiped. Factory reset deletes all recordings stored on the physical device, including active, completed, encrypted, sidecar, and partial-transfer/upload artifacts. It does not delete cloud recordings, transcriptions, summaries, the device record, serial number, or manufacturing identity.

How it works

Bota creates or returns the device’s existing in-flight factory_reset command. The command does not use the normal five-minute command expiry.
The device remains bound and its device token remains valid, but that token is restricted to heartbeat and the exact reset acknowledgement.
A WiFi/4G heartbeat or authenticated Bluetooth relay delivers the command.
The device stops recording/upload work and deletes every local recording.
The device or relay acknowledges the exact command as executed.
Bota atomically marks the command executed, unbinds the device, revokes its device token, and clears device-level configuration.
The device clears its remaining user/project credentials and reboots unpaired.

If an acknowledgement or its HTTP response is lost, the same reset can be retried safely. Bota returns the already-executed result after successful finalization instead of running the backend cleanup twice.

Do not treat command creation or delivery as reset completion. Wait for the command status to become executed. The physical wipe requires a compatible firmware and relay release; older devices leave the command pending and must not be reported as reset.

Authentication

Requires an API key with devices:write scope.

curl -X POST https://api.bota.dev/v1/devices/dev_abc123/reset \
  -H "Authorization: Bearer sk_test_..."

const response = await fetch('https://api.bota.dev/v1/devices/dev_abc123/reset', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTA_API_KEY}`,
  },
});

const resetCommand = await response.json();

import os
import requests

response = requests.post(
    'https://api.bota.dev/v1/devices/dev_abc123/reset',
    headers={'Authorization': f'Bearer {os.environ["BOTA_API_KEY"]}'},
)

reset_command = response.json()

Path Parameters

string

required

The device identifier, for example dev_abc123.

Response

Returns the durable command with HTTP 202 Accepted. Repeating the request while reset is pending or delivered returns the same command.

{
  "id": "cmd_xyz789",
  "device_id": "dev_abc123",
  "type": "factory_reset",
  "status": "pending",
  "params": {},
  "grant_token": "rct_...",
  "result": null,
  "error": null,
  "expires_at": null,
  "delivered_at": null,
  "executed_at": null,
  "created_at": "2026-07-26T08:00:00Z"
}

{
  "error": {
    "code": "resource_not_found",
    "message": "Device not found: dev_abc123"
  }
}

Field	Type	Description
`id`	string	Reset command identifier (`cmd_*`)
`device_id`	string	Target device identifier
`type`	string	Always `factory_reset`
`status`	string	`pending`, `delivered`, `executed`, `failed`, or `cancelled`
`grant_token`	string	Command-bound reset completion credential; treat it as sensitive
`result`	object \| null	On success, may include `local_recordings_deleted` and `acknowledged_by`
`error`	object \| null	Device-reported reset failure
`expires_at`	null	Reset commands are durable and do not use the normal command TTL
`delivered_at`	string \| null	When the command was delivered
`executed_at`	string \| null	When backend finalization completed
`created_at`	string	Command creation timestamp

Complete the reset

After the physical wipe succeeds, acknowledge the exact command:

curl -X POST \
  https://api.bota.dev/v1/devices/dev_abc123/commands/cmd_xyz789/ack \
  -H "Authorization: Bearer rct_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "executed",
    "result": { "local_recordings_deleted": 7 }
  }'

A direct device may use its still-valid dtok_* token for the first ACK. A Bluetooth relay may use a secret key or a restricted project key with devices:write. The command’s rct_* credential is accepted only on this exact device/command ACK route and remains usable for an idempotent retry if backend finalization committed but the success response was lost. Read-only restricted keys can inspect command status but do not receive the credential.

Reset, unbind, and delete

Operation	Physical-device recordings	Cloud recordings	Device token	Device record
Factory reset	Deleted after device executes command	Preserved	Revoked after ACK	Preserved, unbound
Unbind	Preserved	Preserved	Revoked immediately	Preserved, unbound
Delete	Preserved	Preserved according to normal retention	Revoked	Soft-deleted

Use factory reset only when the physical device must be wiped. Use unbind for non-destructive reassignment.

Overview

End Users

Devices

Recordings

Uploads

AI Ask

AI Processing

Resources

Reset Device

How it works

Authentication

Path Parameters

Response

Complete the reset

Reset, unbind, and delete

​How it works

​Authentication

​Path Parameters

​Response

​Complete the reset

​Reset, unbind, and delete

How it works

Authentication

Path Parameters

Response

Complete the reset

Reset, unbind, and delete