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 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" }'
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 Register the wearable device using its serial number. The serial number is printed on the device or packaging.
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" }'
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" }'
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", "started_at": "2025-01-15T09:00:00Z", "ended_at": "2025-01-15T09:30:00Z", "metadata": { "meeting_type": "client_call", "location": "office" } }'
Response: { "id" : "rec_abc123" , "device_id" : "dev_xyz789" , "end_user_id" : "eu_abc123" , "status" : "pending" , "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" }'
Response: { "upload_url" : "https://bota-uploads.s3.amazonaws.com/..." , "expires_at" : "2025-01-15T11:05:00Z" , "headers" : { "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
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_..."
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/recordings/rec_abc123/transcribe \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "language": "en", "diarization": true }'
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_..."
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" : { "id" : "txn_def456" , "recording_id" : "rec_abc123" , "status" : "completed" , "text" : "Hello, thanks for joining us today..." , "segments" : [ ... ] } }
Transcription Result { "id" : "txn_def456" , "recording_id" : "rec_abc123" , "status" : "completed" , "language" : "en" , "duration_ms" : 1800000 , "text" : "Hello, thanks for joining us today. Happy to be here! So let's discuss the project timeline..." , "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 } ], "created_at" : "2025-01-15T10:10:00Z" , "completed_at" : "2025-01-15T10:15:00Z" }
Common Integration Patterns
Your mobile app handles BLE pairing and audio sync using our SDK. Your backend handles Bota API calls.
User logs into your app (your auth)
App pairs with device via Bluetooth using the React Native SDK
App requests upload URL from your backend
Your backend calls Bota API with secret key
SDK uploads audio directly to S3 with retry logic
Your backend triggers transcription
Webhook notifies your backend when complete
See the examples repository for a complete React Native app.
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
