Quickstart

This guide walks you through the complete flow: creating an end user, registering a device, uploading audio, and getting a transcript. By the end, you’ll understand how to integrate Bota into your application.

Prerequisites

A Bota account with API access — Sign up here

Your project API key from the dashboard

You’ll need your API key (sk_live_...) from the dashboard.

Step 1: Create an End User

End users represent the people who wear your devices. They don’t log into Bota — they exist in your project to associate recordings with the right person.

curl -X POST https://api.bota.dev/v1/end-users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_123",
    "name": "John Doe",
    "email": "john@example.com"
  }'

const response = await fetch('https://api.bota.dev/v1/end-users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_id: 'user_123',
    name: 'John Doe',
    email: 'john@example.com',
  }),
});

const endUser = await response.json();
console.log(endUser.id); // eu_abc123

import requests

response = requests.post(
    'https://api.bota.dev/v1/end-users',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'external_id': 'user_123',
        'name': 'John Doe',
        'email': 'john@example.com',
    },
)

end_user = response.json()
print(end_user['id'])  # eu_abc123

Response:

{
  "id": "eu_abc123",
  "external_id": "user_123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-15T10:00:00Z"
}

The external_id lets you link Bota end users to users in your system. Store a mapping between external_id and the Bota id for lookups.

Step 2: Register a Device

curl -X POST https://api.bota.dev/v1/devices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-2025-001234",
    "device_type": "bota_pin_v1"
  }'

const device = await fetch('https://api.bota.dev/v1/devices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    serial_number: 'SN-2025-001234',
    device_type: 'bota_pin_v1',
  }),
}).then(r => r.json());

console.log(device.id); // dev_xyz789

device = requests.post(
    'https://api.bota.dev/v1/devices',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'serial_number': 'SN-2025-001234',
        'device_type': 'bota_pin_v1',
    },
).json()

print(device['id'])  # dev_xyz789

Response:

{
  "id": "dev_xyz789",
  "serial_number": "SN-2025-001234",
  "device_type": "bota_pin_v1",
  "status": "unbound",
  "end_user_id": null,
  "created_at": "2025-01-15T10:01:00Z"
}

Step 3: Bind Device to User

Associate the device with the end user. A device can only be bound to one user at a time.

curl -X POST https://api.bota.dev/v1/devices/dev_xyz789/bind \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_abc123"
  }'

await fetch('https://api.bota.dev/v1/devices/dev_xyz789/bind', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    end_user_id: 'eu_abc123',
  }),
});

requests.post(
    'https://api.bota.dev/v1/devices/dev_xyz789/bind',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'end_user_id': 'eu_abc123',
    },
)

The device status changes from unbound to bound, and all future recordings are automatically associated with this end user.

Step 4: Create a Recording

When the device captures audio, create a recording entry in Bota. This returns a recording ID you’ll use for upload and transcription.

curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "dev_xyz789",
    "recorded_at": "2025-01-15T09:00:00Z",
    "name": "Client call",
    "metadata": {
      "meeting_type": "client_call",
      "location": "office"
    }
  }'

const recording = 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_xyz789',
    recorded_at: '2025-01-15T09:00:00Z',
    name: 'Client call',
    metadata: {
      meeting_type: 'client_call',
      location: 'office',
    },
  }),
}).then(r => r.json());

console.log(recording.id); // rec_abc123

recording = requests.post(
    'https://api.bota.dev/v1/recordings',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'device_id': 'dev_xyz789',
        'recorded_at': '2025-01-15T09:00:00Z',
        'name': 'Client call',
        'metadata': {
            'meeting_type': 'client_call',
            'location': 'office',
        },
    },
).json()

print(recording['id'])  # rec_abc123

Response:

{
  "id": "rec_abc123",
  "device_id": "dev_xyz789",
  "end_user_id": "eu_abc123",
  "name": "Client call",
  "status": "pending",
  "recorded_at": "2025-01-15T09:00:00Z",
  "metadata": {
    "meeting_type": "client_call",
    "location": "office"
  },
  "created_at": "2025-01-15T10:05:00Z"
}

Step 5: Upload Audio

Upload audio in three steps: get a pre-signed URL, upload the file, then mark complete.

5a. 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 '{
    "content_type": "audio/wav"
  }'

const { upload_url, headers } = 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({ content_type: 'audio/wav' }),
  }
).then(r => r.json());

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

upload_url = upload_info['upload_url']

Response:

{
  "upload_url": "https://bota-uploads.s3.amazonaws.com/...",
  "upload_token": "up_abc123",
  "expires_in": 3600,
  "content_type": "audio/wav"
}

5b. Upload to S3

Upload directly to the pre-signed URL. This bypasses the Bota API for faster uploads.

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

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

with open('recording.wav', 'rb') as f:
    requests.put(
        upload_url,
        headers={'Content-Type': 'audio/wav'},
        data=f.read(),
    )

5c. Mark Upload Complete

Tell Bota the upload finished. This triggers validation and updates the recording status.

curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/upload-complete \
  -H "Authorization: Bearer sk_live_..."

await fetch('https://api.bota.dev/v1/recordings/rec_abc123/upload-complete', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_...' },
});

requests.post(
    'https://api.bota.dev/v1/recordings/rec_abc123/upload-complete',
    headers={'Authorization': 'Bearer sk_live_...'},
)

The recording status changes from pending to uploaded.

Step 6: Transcribe

Start an async transcription job. Transcription typically takes 10-30% of the audio duration.

curl -X POST https://api.bota.dev/v1/transcriptions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recording_id": "rec_abc123",
    "language": "en"
  }'

const transcription = await fetch(
  'https://api.bota.dev/v1/transcriptions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ recording_id: 'rec_abc123', language: 'en' }),
  }
).then(r => r.json());

console.log(transcription.id); // txn_def456

transcription = requests.post(
    'https://api.bota.dev/v1/transcriptions',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={'recording_id': 'rec_abc123', 'language': 'en'},
).json()

print(transcription['id'])  # txn_def456

Response:

{
  "id": "txn_def456",
  "recording_id": "rec_abc123",
  "status": "pending",
  "language": "en",
  "created_at": "2025-01-15T10:10:00Z"
}

Step 7: Get Results

Poll the transcription endpoint until status is completed, or use webhooks for real-time notifications.

Option A: Polling

curl https://api.bota.dev/v1/transcriptions/txn_def456 \
  -H "Authorization: Bearer sk_live_..."

async function waitForTranscription(id) {
  while (true) {
    const result = await fetch(
      `https://api.bota.dev/v1/transcriptions/${id}`,
      { headers: { 'Authorization': 'Bearer sk_live_...' } }
    ).then(r => r.json());

    if (result.status === 'completed') return result;
    if (result.status === 'failed') throw new Error(result.error_message);

    await new Promise(r => setTimeout(r, 2000)); // Wait 2 seconds
  }
}

const transcript = await waitForTranscription('txn_def456');

import time

def wait_for_transcription(transcription_id):
    while True:
        result = requests.get(
            f'https://api.bota.dev/v1/transcriptions/{transcription_id}',
            headers={'Authorization': 'Bearer sk_live_...'},
        ).json()

        if result['status'] == 'completed':
            return result
        if result['status'] == 'failed':
            raise Exception(result['error_message'])

        time.sleep(2)

transcript = wait_for_transcription('txn_def456')

Option B: Webhooks (Recommended)

Configure a webhook endpoint to receive notifications when transcription completes. See the Webhooks Guide for setup instructions.

// Webhook payload
{
  "id": "evt_abc123",
  "type": "transcription.completed",
  "created_at": "2025-01-15T10:15:00Z",
  "data": {
    "transcription": {
      "id": "txn_def456",
      "recording_id": "rec_abc123",
      "status": "completed"
    }
  }
}

Transcription Result

{
  "id": "txn_def456",
  "recording_id": "rec_abc123",
  "status": "completed",
  "language": "en",
  "provider": "whisper",
  "full_text": "Hello, thanks for joining us today. Happy to be here! So let's discuss the project timeline...",
  "word_count": 18,
  "confidence": 0.95,
  "error_message": null,
  "segments": [
    {
      "text": "Hello, thanks for joining us today.",
      "speaker": "SPEAKER_0",
      "start": 0.0,
      "end": 2.5,
      "confidence": 0.97
    },
    {
      "text": "Happy to be here!",
      "speaker": "SPEAKER_1",
      "start": 2.8,
      "end": 4.2,
      "confidence": 0.95
    },
    {
      "text": "So let's discuss the project timeline...",
      "speaker": "SPEAKER_0",
      "start": 4.5,
      "end": 7.1,
      "confidence": 0.94
    }
  ],
  "started_at": "2025-01-15T10:10:01Z",
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:15:00Z",
  "updated_at": "2025-01-15T10:15:00Z"
}

Common Integration Patterns

Mobile App Integration

Your mobile app handles Bluetooth pairing and audio sync using our SDK. Your backend handles Bota API calls.

User logs into your app (your auth)
App connects through the Bota App SDK and verifies the device’s exact serial
App requests upload URL from your backend
Your backend calls Bota API with secret key
SDK uploads audio to scoped storage; the host completion callback waits for backend acknowledgement before native cleanup or device confirmation. Restart recovery needs the documented scoped host integration.
After verified upload completion, your backend creates a transcription with POST /v1/transcriptions if automatic transcription is disabled
Webhook notifies your backend when complete

Start with the independent examples. The connection samples are read-only. The repository’s legacy app/backend pair has compatibility and local-only authentication limits; a target-complete recording-sync replacement is not yet available.

Lazy vs Eager EndUser Creation

Lazy (Recommended): Create Bota EndUser on first device pairing. Simpler, no unused records.Eager: Create Bota EndUser at signup. Faster first device pairing, but requires cleanup if user never pairs.

Handling Device Reassignment

When a user leaves or device changes hands:

Unbind the device: POST /devices/{id}/unbind
Optionally delete old recordings
Bind to new user: POST /devices/{id}/bind

Device tokens are automatically rotated on unbind.

What’s Next?

Client SDKs

React Native SDK for mobile app integration

Set Up Webhooks

Get real-time notifications instead of polling

Authentication Deep Dive

Learn about API key types and security best practices

API Reference

Explore the complete API documentation

Getting Started

Features

Hardware

Webhooks

Legal & Compliance

Prerequisites

Step 1: Create an End User

Step 2: Register a Device

Step 3: Bind Device to User

Step 4: Create a Recording

Step 5: Upload Audio

5a. Get Upload URL

5b. Upload to S3

5c. Mark Upload Complete

Step 6: Transcribe

Step 7: Get Results

Option A: Polling

Option B: Webhooks (Recommended)

Transcription Result

Common Integration Patterns

What’s Next?

Client SDKs

Set Up Webhooks

Authentication Deep Dive

API Reference

​Prerequisites

​Step 1: Create an End User

​Step 2: Register a Device

​Step 3: Bind Device to User

​Step 4: Create a Recording

​Step 5: Upload Audio

​5a. Get Upload URL

​5b. Upload to S3

​5c. Mark Upload Complete

​Step 6: Transcribe

​Step 7: Get Results

​Option A: Polling

​Option B: Webhooks (Recommended)

​Transcription Result

​Common Integration Patterns

​What’s Next?

Client SDKs

Set Up Webhooks

Authentication Deep Dive

API Reference

Prerequisites

Step 1: Create an End User

Step 2: Register a Device

Step 3: Bind Device to User

Step 4: Create a Recording

Step 5: Upload Audio

5a. Get Upload URL

5b. Upload to S3

5c. Mark Upload Complete

Step 6: Transcribe

Step 7: Get Results

Option A: Polling

Option B: Webhooks (Recommended)

Transcription Result

Common Integration Patterns

What’s Next?