> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Bota REST API

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:

```bash theme={null}
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](/api-reference/test-mode)) |
| **Device Token** | `dtok_*`    | Hours/days | Device authentication                                         |
| **Upload Token** | `up_*`      | Minutes    | Single file upload                                            |

<Warning>
  Never expose secret keys (`sk_*`) in client-side code, mobile apps, or public repositories.
</Warning>

See [Authentication](/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:

```bash theme={null}
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

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

### List Response

List endpoints return paginated results:

```json theme={null}
{
  "data": [
    { "id": "eu_abc123", "name": "John Doe" },
    { "id": "eu_def456", "name": "Jane Smith" }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImV1X2RlZjQ1NiJ9"
}
```

### Error Response

```json theme={null}
{
  "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](/api-reference/errors) for detailed error codes and handling strategies.

***

## Pagination

List endpoints support cursor-based pagination:

```bash theme={null}
# 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](/api-reference/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](/api-reference/rate-limits) for handling 429 responses.

***

## Idempotency

For safe retries, include an `Idempotency-Key` header on POST requests:

```bash theme={null}
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](/api-reference/idempotency) for best practices.

***

## Versioning

The API uses date-based versioning. Specify a version to pin your integration:

```bash theme={null}
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](/api-reference/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:

<CardGroup cols={2}>
  <Card title="End Users" icon="users" href="/api-reference/end-users/create">
    People who wear devices. Create, list, and delete end users with external ID mapping.
  </Card>

  <Card title="Devices" icon="microchip" href="/api-reference/devices/create">
    Physical wearables. Register devices, bind to users, track fleet status.
  </Card>

  <Card title="Recordings" icon="circle-dot" href="/api-reference/recordings/create">
    Captured conversations. Create entries, upload audio, track processing status.
  </Card>

  <Card title="Uploads" icon="cloud-arrow-up" href="/api-reference/uploads/create-url">
    Audio file ingestion. Get pre-signed URLs for direct S3 upload.
  </Card>

  <Card title="Transcriptions" icon="file-lines" href="/api-reference/transcriptions/create">
    Speech-to-text processing. Start jobs, get results with speaker diarization.
  </Card>

  <Card title="Summaries" icon="sparkles" href="/api-reference/summaries/create">
    AI-generated summaries. Create summaries from transcriptions.
  </Card>

  <Card title="Webhooks" icon="bell" href="/webhooks/overview">
    Event notifications. Set up endpoints for real-time updates.
  </Card>
</CardGroup>

***

## SDKs & Tools

<CardGroup cols={2}>
  <Card title="OpenAPI Spec" icon="file-code" href="/api-reference/openapi">
    Download the OpenAPI 3.0 specification for code generation
  </Card>

  <Card title="Postman Collection" icon="rocket" href="/api-reference/postman">
    Import our Postman collection for interactive testing
  </Card>
</CardGroup>

Official SDKs (coming soon):

* Node.js / TypeScript
* Python
* Go

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Complete tutorial from first API call to transcription
  </Card>

  <Card title="Support" icon="headset" href="/support">
    Contact our team for integration help
  </Card>
</CardGroup>