Create Recording

# 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"
    }
  }'

# Using Device Token - do NOT include device_id or end_user_id
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer dtok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2025-01-15T09:00:00Z",
    "codec": "opus_16k"
  }'

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',
    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',
    },
  }),
});

const recording = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'device_id': 'dev_abc123',
        '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',
        },
    },
)

recording = response.json()

{
  "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"
}

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"
    }
  }'

# Using Device Token - do NOT include device_id or end_user_id
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer dtok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2025-01-15T09:00:00Z",
    "codec": "opus_16k"
  }'

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',
    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',
    },
  }),
});

const recording = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'device_id': 'dev_abc123',
        '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',
        },
    },
)

recording = response.json()

{
  "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"
}

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 Bluetooth 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"
    }
  }'

# Using Device Token - do NOT include device_id or end_user_id
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer dtok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2025-01-15T09:00:00Z",
    "codec": "opus_16k"
  }'

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',
    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',
    },
  }),
});

const recording = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'device_id': 'dev_abc123',
        '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',
        },
    },
)

recording = response.json()

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

Field	Type	Description
`id`	string	Unique identifier for the recording (`rec_*`).
`device_id`	string	ID of the device that captured the recording.
`end_user_id`	string	ID of the associated end user.
`name`	string	Human-readable name for the recording.
`status`	string	Current recording status (see below).
`duration_ms`	integer \| null	Recording duration in milliseconds. `null` until audio is uploaded.
`started_at`	string	ISO 8601 timestamp of when the recording started.
`ended_at`	string	ISO 8601 timestamp of when the recording ended.
`transcription_id`	string \| null	ID of the associated transcription. `null` until transcription is created.
`media`	array	Files associated with this recording (audio, images, video). Empty until uploaded.
`media[].id`	string	Media identifier (`med_*`).
`media[].type`	string	Media type: `audio`, `image`, or `video`.
`media[].mime_type`	string	MIME type (e.g., `audio/opus`, `image/jpeg`, `video/mp4`).
`media[].file_size_bytes`	integer	File size in bytes.
`media[].status`	string	Upload status: `pending`, `uploaded`.
`media[].captured_at`	string \| null	ISO 8601 timestamp of when the media was captured.
`media[].created_at`	string	ISO 8601 timestamp of when the media record was created.
`metadata`	object	Arbitrary key-value metadata.
`created_at`	string	ISO 8601 timestamp of when the recording was created.

Recording Status

Status	Description
`pending`	Recording created, awaiting audio upload
`uploaded`	Audio uploaded, ready for transcription
`processing`	Transcription in progress
`completed`	Transcription complete
`failed`	Processing failed

Next Steps

After creating a recording:

Get an upload URL
Upload audio to the pre-signed S3 URL
Mark upload complete
Trigger transcription

Cancel Recording Command Finalize Streaming Recording

​Authentication

​Request Body

​Response

​Response Fields

​Recording Status

​Next Steps

Authentication

Request Body

Response

Response Fields

Recording Status

Next Steps