Skip to main content
POST
/
recordings
# Using API Key - include device_id and end_user_id
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",
    "started_at": "2025-01-15T09:00:00Z",
    "ended_at": "2025-01-15T09:30:00Z",
    "metadata": {
      "meeting_type": "interview",
      "location": "office"
    }
  }'

{
  "id": "rec_abc123",
  "device_id": "dev_abc123",
  "end_user_id": "eu_xyz789",
  "name": "Product interview - Jane Doe",
  "status": "pending",
  "duration_ms": null,
  "started_at": "2025-01-15T09:00:00Z",
  "ended_at": "2025-01-15T09:30:00Z",
  "transcription_id": null,
  "media": [],
  "metadata": {
    "meeting_type": "interview",
    "location": "office"
  },
  "created_at": "2025-01-15T10:00:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bota.dev/llms.txt

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

Create a recording to represent a captured conversation. After creation, use the upload endpoints to upload the audio file.

​
Authentication

This endpoint behaves differently depending on your authentication method: Using API Keys:
  • Required: device_id and end_user_id in request body
  • Use case: Mobile apps uploading on behalf of users via BLE sync
Using Device Tokens:
  • Required: Neither device_id nor end_user_id (automatically extracted from token)
  • Use case: 4G/WiFi devices uploading directly to the cloud
See the examples below for both scenarios. 
# Using API Key - include device_id and end_user_id
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",
    "started_at": "2025-01-15T09:00:00Z",
    "ended_at": "2025-01-15T09:30:00Z",
    "metadata": {
      "meeting_type": "interview",
      "location": "office"
    }
  }'

​
Request Body

​
device_id
string
ID of the device that captured (or will capture) the recording. Optional for API-uploaded audio files.Note: When using device tokens (dtok_*), this field is automatically populated from the token and should NOT be included in the request.
​
end_user_id
string
ID of the end user. Required when using API keys.Note: When using device tokens (dtok_*), this field is automatically populated from the token and should NOT be included in the request.
​
name
string
Optional human-readable name for the recording (e.g., “Weekly standup”, “Client call with Acme”).
​
started_at
string
ISO 8601 timestamp of when the recording started (device time).
​
ended_at
string
ISO 8601 timestamp of when the recording ended (device time).
​
metadata
object
Arbitrary key-value metadata (e.g., meeting type, location).

​
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_ms": null,
  "started_at": "2025-01-15T09:00:00Z",
  "ended_at": "2025-01-15T09:30:00Z",
  "transcription_id": null,
  "media": [],
  "metadata": {
    "meeting_type": "interview",
    "location": "office"
  },
  "created_at": "2025-01-15T10:00:00Z"
}

​
Response Fields

FieldTypeDescription
idstringUnique identifier for the recording (rec_*).
device_idstringID of the device that captured the recording.
end_user_idstringID of the associated end user.
namestringHuman-readable name for the recording.
statusstringCurrent recording status (see below).
duration_msinteger | nullRecording duration in milliseconds. null until audio is uploaded.
started_atstringISO 8601 timestamp of when the recording started.
ended_atstringISO 8601 timestamp of when the recording ended.
transcription_idstring | nullID of the associated transcription. null until transcription is created.
mediaarrayFiles associated with this recording (audio, images, video). Empty until uploaded.
media[].idstringMedia identifier (med_*).
media[].typestringMedia type: audio, image, or video.
media[].mime_typestringMIME type (e.g., audio/opus, image/jpeg, video/mp4).
media[].file_size_bytesintegerFile size in bytes.
media[].statusstringUpload status: pending, uploaded.
media[].captured_atstring | nullISO 8601 timestamp of when the media was captured.
media[].created_atstringISO 8601 timestamp of when the media record was created.
metadataobjectArbitrary key-value metadata.
created_atstringISO 8601 timestamp of when the recording was created.

​
Recording Status

StatusDescription
pendingRecording created, awaiting audio upload
uploadedAudio uploaded, ready for transcription
processingTranscription in progress
completedTranscription complete
failedProcessing failed

​
Next Steps

After creating a recording:
  1. Get an upload URL
  2. Upload audio to the pre-signed S3 URL
  3. Mark upload complete
  4. Trigger transcription