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

# REST API introduction — authentication, base URL & conventions | Burki Docs

> Welcome to the Burki Voice AI API Reference.

# Burki REST API — Introduction

The Burki Voice AI API allows you to programmatically manage assistants, calls, and other resources in your organization. You can use it to build powerful integrations and automate your voice AI workflows.

This API is built on REST principles and uses standard HTTP response codes and authentication. All API responses are returned in JSON format.

## Base URL

All API requests should be made to:

```
https://api.burki.dev
```

## Authentication

Most API endpoints accept a bearer token in the `Authorization` header:

* **API key** (recommended for server-to-server integrations)
* **JWT access token** (for user-authenticated app sessions)

Many dashboard-backed endpoints also support session auth when used from the web app, but external integrations should use API keys.

You can generate and manage API keys in your dashboard at [burki.dev/dashboard](https://burki.dev/dashboard).

### Bearer Authentication Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.burki.dev/api/v1/assistants" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  api_key = "YOUR_API_KEY"
  headers = {
      "Authorization": f"Bearer {api_key}"
  }

  response = requests.get(
      "https://api.burki.dev/api/v1/assistants", 
      headers=headers
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  const apiKey = 'YOUR_API_KEY';

  fetch('https://api.burki.dev/api/v1/assistants', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  })
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
  ```
</CodeGroup>

<Warning>
  Treat your API keys like passwords! Do not share them publicly or commit them to version control.
</Warning>

## Response Format

Responses are JSON, but shape varies by endpoint. Two common patterns:

### Resource/List Responses

```json theme={null}
[
  {
    "id": 123,
    "name": "Customer Service Bot"
  }
]
```

```json theme={null}
{
  "items": [],
  "total": 0,
  "skip": 0,
  "limit": 100
}
```

### Error Response (FastAPI style)

```json theme={null}
{
  "detail": "Error description"
}
```

## Error Codes

| Code  | Description                                                 |
| ----- | ----------------------------------------------------------- |
| `400` | Bad Request - Invalid parameters                            |
| `401` | Unauthorized - Invalid or missing API key                   |
| `403` | Forbidden - Insufficient permissions                        |
| `404` | Not Found - Resource doesn't exist                          |
| `429` | Too Many Requests - Endpoint or account rate limit exceeded |
| `500` | Internal Server Error                                       |

## Rate Limits

Rate limiting is endpoint-specific and can vary by auth type and environment configuration.

* Expect `429 Too Many Requests` when limits are exceeded.
* Some endpoints include `Retry-After` in the response headers.
* Build clients with retry/backoff for transient limit errors.

For critical workloads, contact Burki support for current limits and throughput planning.

## Pagination

Most list endpoints use `skip` + `limit` pagination:

| Parameter | Description                         | Default           |
| --------- | ----------------------------------- | ----------------- |
| `skip`    | Number of records to skip           | `0`               |
| `limit`   | Maximum number of records to return | endpoint-specific |

Common paginated response shape:

```json theme={null}
{
  "items": [...],
  "total": 100,
  "skip": 0,
  "limit": 100
}
```

## Webhooks

Burki can send webhook notifications for various events. Configure webhooks in your dashboard under **Settings** → **Webhooks**.

Current webhook payloads are sent as typed JSON messages:

* Voice call lifecycle webhooks use `message.type` values such as:
  * `status-update`
  * `end-of-call-report`
* SMS webhooks use top-level `type` such as:
  * `sms_received`

Always parse webhook payloads by their explicit `type` field instead of assuming dotted event names.

## SDKs & Libraries

Official SDKs are available for Python, JavaScript/TypeScript, and Go:

| Language                  | Package                        | Installation                          |
| ------------------------- | ------------------------------ | ------------------------------------- |
| **Python**                | `burki`                        | `pip install burki`                   |
| **JavaScript/TypeScript** | `@burki.dev/sdk`               | `npm install @burki.dev/sdk`          |
| **Go**                    | `github.com/burki-ai/burki-go` | `go get github.com/burki-ai/burki-go` |

<CardGroup cols={2}>
  <Card title="SDK Overview" icon="code" href="/sdks/overview">
    Compare SDKs and get started quickly
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    Full Python SDK documentation
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdks/javascript">
    TypeScript-first SDK with full types
  </Card>

  <Card title="Go SDK" icon="golang" href="/sdks/go">
    Idiomatic Go SDK with channels
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with Burki in 5 minutes
  </Card>

  <Card title="Assistants API" icon="robot" href="/api-reference/assistants/create">
    Create and manage AI assistants
  </Card>
</CardGroup>