curl -X POST https://api.bota.dev/v1/recordings \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"recorded_at": "2025-01-15T09:00:00Z",
"source": "device",
"upload_method": "ble",
"metadata": {
"meeting_type": "interview"
}
}'
const response = await fetch('https://api.bota.dev/v1/recordings', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
device_id: 'dev_abc123',
end_user_id: 'eu_xyz789',
name: 'Product interview - Jane Doe',
recorded_at: '2025-01-15T09:00:00Z',
}),
});
const recording = await response.json();
{
"id": "rec_abc123",
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"status": "pending",
"duration_seconds": null,
"file_size_bytes": null,
"recorded_at": "2025-01-15T09:00:00Z",
"metadata": {
"meeting_type": "interview"
},
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
Recordings
Create Recording
Create a recording record before uploading audio
POST
/
recordings
curl -X POST https://api.bota.dev/v1/recordings \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"recorded_at": "2025-01-15T09:00:00Z",
"source": "device",
"upload_method": "ble",
"metadata": {
"meeting_type": "interview"
}
}'
const response = await fetch('https://api.bota.dev/v1/recordings', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
device_id: 'dev_abc123',
end_user_id: 'eu_xyz789',
name: 'Product interview - Jane Doe',
recorded_at: '2025-01-15T09:00:00Z',
}),
});
const recording = await response.json();
{
"id": "rec_abc123",
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"status": "pending",
"duration_seconds": null,
"file_size_bytes": null,
"recorded_at": "2025-01-15T09:00:00Z",
"metadata": {
"meeting_type": "interview"
},
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
Create a recording to represent captured audio. After creation, use the upload endpoints to upload the audio file.
Authentication
This endpoint accepts either an API key or a device token. Device tokens automatically bind the recording to the token’s device and end user.curl -X POST https://api.bota.dev/v1/recordings \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"recorded_at": "2025-01-15T09:00:00Z",
"source": "device",
"upload_method": "ble",
"metadata": {
"meeting_type": "interview"
}
}'
const response = await fetch('https://api.bota.dev/v1/recordings', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
device_id: 'dev_abc123',
end_user_id: 'eu_xyz789',
name: 'Product interview - Jane Doe',
recorded_at: '2025-01-15T09:00:00Z',
}),
});
const recording = await response.json();
Request Body
string
ID of the device that captured the recording. Device tokens set this automatically.
string
ID of the end user associated with the recording. Device tokens set this automatically.
string
Optional human-readable name.
string
ISO 8601 timestamp for when the audio was recorded.
object
Arbitrary key-value metadata.
boolean
Set to
true for chunked streaming uploads.string
Upload method. Supported values include
ble, wifi_direct, 4g_direct, import, and unknown.string
Audio source. Supported values are
device, app_import, and api_upload.integer
Optional storage encryption audit version.
Response
Returns the created recording object.{
"id": "rec_abc123",
"device_id": "dev_abc123",
"end_user_id": "eu_xyz789",
"name": "Product interview - Jane Doe",
"status": "pending",
"duration_seconds": null,
"file_size_bytes": null,
"recorded_at": "2025-01-15T09:00:00Z",
"metadata": {
"meeting_type": "interview"
},
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
}
Recording Status
| Status | Description |
|---|---|
pending | Recording created, awaiting audio upload |
streaming | Chunked streaming upload in progress |
uploaded | Audio uploaded, ready for transcription |
processing | Processing in progress |
completed | Processing complete |
failed | Processing failed |
integrity_failure | Uploaded audio failed SHA-256 verification |
Next Steps
- Get an upload URL, or use chunk URLs for streaming uploads
- Upload audio to S3
- Mark upload complete or finalize streaming
- Create a transcription
Was this page helpful?

