API Reference

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

Type	Prefix	Lifespan	Use Case
Secret Key	`sk_live_*`	Long-lived	Server-side API access
Test Key	`sk_test_*`	Long-lived	Development & testing (Test Mode)
Device Token	`dtok_*`	Hours/days	Device authentication
Upload Token	`up_*`	Minutes	Single 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

Header	Required	Description
`Authorization`	Yes	Bearer token: `Bearer sk_live_...`
`Content-Type`	For POST/PUT	`application/json`
`Idempotency-Key`	Recommended	Unique key for safe retries
`Bota-Version`	Optional	API 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

Code	Description
`200`	Success
`201`	Created
`204`	No content (successful deletion)
`400`	Bad request — invalid parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not found
`409`	Conflict — resource already exists
`422`	Unprocessable — validation error
`429`	Rate limited
`500`	Server 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_..."

Parameter	Type	Description
`limit`	integer	Items per page (default: 20, max: 100)
`cursor`	string	Cursor from previous response

See Pagination for details.

Rate Limits

The API enforces rate limits to ensure fair usage:

Limit	Value
Requests per second	100
Requests per minute	1,000
Concurrent uploads	10

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 Prefix	Environment	Purpose
`sk_live_*`	Production	Live data, billed usage
`sk_test_*`	Test	Development 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

​Base URL

​Authentication

​API Key Types

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​List Response

​Error Response

​HTTP Status Codes

​Pagination

​Rate Limits

​Idempotency

​Versioning

​Test Mode

​Core Resources

End Users

Devices

Recordings

Uploads

Transcriptions

Summaries

Webhooks

​SDKs & Tools

OpenAPI Spec

Postman Collection

​Need Help?

Quickstart

Support

Base URL

Authentication

API Key Types

Request Format

Headers

Request Body

Response Format

Success Response

List Response

Error Response

HTTP Status Codes

Pagination

Rate Limits

Idempotency

Versioning

Test Mode

Core Resources

SDKs & Tools

Need Help?