Skip to main content
The Bota API is a RESTful API for managing conversation capture devices, audio uploads, transcription, and summarization. This page covers the fundamentals you need to integrate with the API.

​
Base URL

All API requests are made to: 
https://api.bota.dev/v1

​
Authentication

Authenticate requests using Bearer tokens in the Authorization header: 
curl https://api.bota.dev/v1/end-users \
  -H "Authorization: Bearer sk_live_abc123..."

​
API Key Types

TypePrefixLifespanUse Case
Secret Keysk_live_*Long-livedServer-side API access
Test Keysk_test_*Long-livedDevelopment & testing (Test Mode)
Device Tokendtok_*Hours/daysDevice authentication
Upload Tokenup_*MinutesSingle file upload
Never expose secret keys (sk_*) in client-side code, mobile apps, or public repositories.
See Authentication for detailed guidance on key management and security.

​
Request Format

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token: Bearer sk_live_...
Content-TypeFor POST/PUTapplication/json
Idempotency-KeyRecommendedUnique key for safe retries
Bota-VersionOptionalAPI version date (e.g., 2025-01-15)

​
Request Body

Send JSON in the request body for POST and PUT requests: 
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"
  }'

​
Response Format

All responses return JSON with consistent structure.

​
Success Response

{
  "id": "eu_abc123",
  "external_id": "user_123",
  "name": "John Doe",
  "created_at": "2025-01-15T10:00:00Z"
}

​
List Response

List endpoints return paginated results: 
{
  "data": [
    { "id": "eu_abc123", "name": "John Doe" },
    { "id": "eu_def456", "name": "Jane Smith" }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImV1X2RlZjQ1NiJ9"
}

​
Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'external_id' field is required",
    "param": "external_id",
    "request_id": "req_abc123"
  }
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
204No content (successful deletion)
400Bad request — invalid parameters
401Unauthorized — invalid or missing API key
403Forbidden — insufficient permissions
404Not found
409Conflict — resource already exists
422Unprocessable — validation error
429Rate limited
500Server error
See Errors for detailed error codes and handling strategies.

​
Pagination

List endpoints support cursor-based pagination: 
# First page
curl "https://api.bota.dev/v1/recordings?limit=20" \
  -H "Authorization: Bearer sk_live_..."

# Next page
curl "https://api.bota.dev/v1/recordings?limit=20&cursor=eyJpZCI6InJlY18xMjMifQ" \
  -H "Authorization: Bearer sk_live_..."
ParameterTypeDescription
limitintegerItems per page (default: 20, max: 100)
cursorstringCursor from previous response
See Pagination for details.

​
Rate Limits

The API enforces rate limits to ensure fair usage:
LimitValue
Requests per second100
Requests per minute1,000
Concurrent uploads10
Rate limit headers are included in every response: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000
See Rate Limits for handling 429 responses.

​
Idempotency

For safe retries, include an Idempotency-Key header on POST requests: 
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: rec_create_user123_1705320000" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "dev_xyz789"}'
Replaying a request with the same key returns the original response without creating duplicates. See Idempotency for best practices.

​
Versioning

The API uses date-based versioning. Specify a version to pin your integration: 
curl https://api.bota.dev/v1/end-users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Bota-Version: 2025-01-15"
Without a version header, requests use the latest stable version. See Versioning for migration guidance.

​
Test Mode

Use test API keys (sk_test_*) to develop and test your integration without affecting production data or incurring charges.
Key PrefixEnvironmentPurpose
sk_live_*ProductionLive data, billed usage
sk_test_*TestDevelopment and testing
Test mode features:
  • Data is isolated from production
  • No billing or usage charges
  • Create separate projects for staging/development environments

​
Core Resources

The API is organized around these resources:

End Users

People who wear devices. Create, list, and delete end users with external ID mapping.

Devices

Physical wearables. Register devices, bind to users, track fleet status.

Recordings

Captured conversations. Create entries, upload audio, track processing status.

Uploads

Audio file ingestion. Get pre-signed URLs for direct S3 upload.

Transcriptions

Speech-to-text processing. Start jobs, get results with speaker diarization.

Summaries

AI-generated summaries. Create summaries from transcriptions.

Webhooks

Event notifications. Set up endpoints for real-time updates.

​
SDKs & Tools

OpenAPI Spec

Download the OpenAPI 3.0 specification for code generation

Postman Collection

Import our Postman collection for interactive testing
Official SDKs (coming soon):
  • Node.js / TypeScript
  • Python
  • Go

​
Need Help?

Quickstart

Complete tutorial from first API call to transcription

Support

Contact our team for integration help