Get Upload URL

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "audio",
    "content_type": "audio/opus",
    "file_size_bytes": 2048576
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "content_type": "image/jpeg",
    "file_size_bytes": 245000,
    "captured_at": "2025-01-15T09:05:30Z"
  }'

const response = await fetch('https://api.bota.dev/v1/recordings/rec_abc123/upload-url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'audio',
    content_type: 'audio/opus',
    file_size_bytes: 2048576,
  }),
});

const { media_id, upload_url, headers, expires_at } = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings/rec_abc123/upload-url',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'type': 'audio',
        'content_type': 'audio/opus',
        'file_size_bytes': 2048576,
    },
)

result = response.json()
upload_url = result['upload_url']

{
  "media_id": "med_001",
  "upload_url": "https://bota-uploads.s3.amazonaws.com/proj_xxx/rec_abc123/med_001/audio.opus?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expires_at": "2025-01-15T12:00:00Z",
  "headers": {
    "Content-Type": "audio/opus"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Recording not found"
  }
}

POST

recordings

{id}

upload-url

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "audio",
    "content_type": "audio/opus",
    "file_size_bytes": 2048576
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "content_type": "image/jpeg",
    "file_size_bytes": 245000,
    "captured_at": "2025-01-15T09:05:30Z"
  }'

const response = await fetch('https://api.bota.dev/v1/recordings/rec_abc123/upload-url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'audio',
    content_type: 'audio/opus',
    file_size_bytes: 2048576,
  }),
});

const { media_id, upload_url, headers, expires_at } = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings/rec_abc123/upload-url',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'type': 'audio',
        'content_type': 'audio/opus',
        'file_size_bytes': 2048576,
    },
)

result = response.json()
upload_url = result['upload_url']

{
  "media_id": "med_001",
  "upload_url": "https://bota-uploads.s3.amazonaws.com/proj_xxx/rec_abc123/med_001/audio.opus?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expires_at": "2025-01-15T12:00:00Z",
  "headers": {
    "Content-Type": "audio/opus"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Recording not found"
  }
}

Generate a pre-signed S3 URL for uploading a file to a recording. Supports audio, image, and video files. Upload the file directly to S3 using the returned URL. After all files are uploaded, call the Complete Upload endpoint.

Authentication

This endpoint accepts two authentication methods:

Auth	Use case
API key	Backend uploading on behalf of devices (BLE sync)
Device token	4G/WiFi devices uploading directly

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "audio",
    "content_type": "audio/opus",
    "file_size_bytes": 2048576
  }'

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "content_type": "image/jpeg",
    "file_size_bytes": 245000,
    "captured_at": "2025-01-15T09:05:30Z"
  }'

const response = await fetch('https://api.bota.dev/v1/recordings/rec_abc123/upload-url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'audio',
    content_type: 'audio/opus',
    file_size_bytes: 2048576,
  }),
});

const { media_id, upload_url, headers, expires_at } = await response.json();

import requests

response = requests.post(
    'https://api.bota.dev/v1/recordings/rec_abc123/upload-url',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'type': 'audio',
        'content_type': 'audio/opus',
        'file_size_bytes': 2048576,
    },
)

result = response.json()
upload_url = result['upload_url']

Path Parameters

string

required

The recording’s unique identifier (e.g., rec_abc123).

Request Body

type

string

required

Media type: audio, image, or video.

content_type

string

MIME type of the file. Defaults based on type:

Audio (default: audio/opus): audio/opus, audio/wav, audio/mpeg, audio/mp4, audio/webm, audio/ogg, audio/flac
Image: image/jpeg, image/png
Video: video/mp4

file_size_bytes

integer

Expected file size in bytes. Used for validation.

captured_at

string

ISO 8601 timestamp of when the media was captured. Used to align images/video with the recording timeline. Optional for audio.

Response

Returns a media record ID, a pre-signed S3 upload URL, required headers, and an expiration timestamp.

{
  "media_id": "med_001",
  "upload_url": "https://bota-uploads.s3.amazonaws.com/proj_xxx/rec_abc123/med_001/audio.opus?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expires_at": "2025-01-15T12:00:00Z",
  "headers": {
    "Content-Type": "audio/opus"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Recording not found"
  }
}

Response Fields

Field	Type	Description
`media_id`	string	Identifier for the created media record (`med_*`)
`upload_url`	string	Pre-signed S3 URL for uploading the file via PUT request
`expires_at`	string	ISO 8601 timestamp when the upload URL expires (1 hour from creation)
`headers`	object	HTTP headers to include when uploading to S3 (e.g., `Content-Type`)

Uploading the File

After obtaining the pre-signed URL, upload the file directly to S3:

cURL

curl -X PUT "https://bota-uploads.s3.amazonaws.com/..." \
  -H "Content-Type: audio/opus" \
  --data-binary @recording.opus

Node.js

const fs = require('fs');

const audioBuffer = fs.readFileSync('recording.opus');

await fetch(upload_url, {
  method: 'PUT',
  headers: {
    'Content-Type': 'audio/opus',
  },
  body: audioBuffer,
});

Python

with open('recording.opus', 'rb') as f:
    audio_data = f.read()

requests.put(
    upload_url,
    headers={'Content-Type': 'audio/opus'},
    data=audio_data,
)

Multi-File Upload

A single recording can have multiple media files. Call this endpoint once per file:

// 1. Create recording
const recording = await createRecording({ device_id: 'dev_abc123' });

// 2. Upload audio
const audio = await getUploadUrl(recording.id, {
  type: 'audio',
  content_type: 'audio/opus',
});
await uploadToS3(audio.upload_url, audioBuffer, 'audio/opus');

// 3. Upload images captured during the recording
const image1 = await getUploadUrl(recording.id, {
  type: 'image',
  content_type: 'image/jpeg',
  captured_at: '2025-01-15T09:05:30Z',
});
await uploadToS3(image1.upload_url, imageBuffer1, 'image/jpeg');

const image2 = await getUploadUrl(recording.id, {
  type: 'image',
  content_type: 'image/jpeg',
  captured_at: '2025-01-15T09:15:00Z',
});
await uploadToS3(image2.upload_url, imageBuffer2, 'image/jpeg');

// 4. Mark complete — fires event for downstream processing
await completeUpload(recording.id);

Upload URLs expire after 1 hour. If expired, request a new URL. After all files are uploaded, call the Complete Upload endpoint to finalize.

Search Recordings Get Download URL

​Authentication

​Path Parameters

​Request Body

​Response

​Response Fields

​Uploading the File

​Multi-File Upload

Authentication

Path Parameters

Request Body

Response

Response Fields

Uploading the File

Multi-File Upload