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

# API overview

> Authenticate, understand rate limits, and work with the OpenWhispr REST API.

The OpenWhispr API lets you manage notes, folders, transcriptions, and usage programmatically. All endpoints live under `/api/v1` and require an API key.

## Base URL

```
https://api.openwhispr.com/api/v1
```

## Authentication

Every request needs a Bearer token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer owk_live_YOUR_KEY" \
  https://api.openwhispr.com/api/v1/notes/list
```

Generate API keys from the OpenWhispr desktop app under **Integrations > API Keys**. Keys start with `owk_live_` and are shown once at creation.

### Scopes

Each key has scoped permissions. Requests missing the required scope get a `403 Forbidden` response.

| Scope                 | Access                                            |
| --------------------- | ------------------------------------------------- |
| `notes:read`          | List, get, and search notes. List folders.        |
| `notes:write`         | Create, update, and delete notes. Create folders. |
| `transcriptions:read` | List and get transcription history.               |
| `usage:read`          | Read usage statistics.                            |

## Response format

All responses use a consistent envelope.

<CodeGroup>
  ```json Single resource theme={null}
  {
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Meeting notes",
      "content": "Discussed the roadmap..."
    }
  }
  ```

  ```json Paginated list theme={null}
  {
    "data": [
      { "id": "...", "title": "Note 1" },
      { "id": "...", "title": "Note 2" }
    ],
    "has_more": true,
    "next_cursor": "2026-04-15T10:30:00.000Z"
  }
  ```

  ```json Error theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Note not found"
    }
  }
  ```
</CodeGroup>

## Pagination

List endpoints use cursor-based pagination. Pass the `next_cursor` value from a previous response as the `cursor` query parameter.

```bash theme={null}
# First page
curl -H "Authorization: Bearer $KEY" \
  "https://api.openwhispr.com/api/v1/notes/list?limit=50"

# Next page
curl -H "Authorization: Bearer $KEY" \
  "https://api.openwhispr.com/api/v1/notes/list?limit=50&cursor=2026-04-15T10:30:00.000Z"
```

When `has_more` is `false`, you've reached the end.

## Rate limits

Limits are per API key with minute and daily windows. Search requests cost 5x.

| Plan     | Per minute | Per day |
| -------- | ---------- | ------- |
| Free     | 30         | 1,000   |
| Pro      | 120        | 10,000  |
| Business | 300        | 50,000  |

Every response includes rate limit headers:

| Header                  | Description                       |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Max requests per minute           |
| `X-RateLimit-Remaining` | Remaining in current window       |
| `X-RateLimit-Reset`     | Unix timestamp when window resets |
| `Retry-After`           | Seconds to wait (only on `429`)   |