API overview

The OpenWhispr API lets you manage notes, folders, transcriptions, and usage programmatically. All endpoints live under /api/v1. Most require an API key — the exceptions are covered below.

Base URL

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

Authentication

Most requests need a Bearer token in the Authorization header.

curl -H "Authorization: Bearer owk_live_YOUR_KEY" \
  https://api.openwhispr.com/api/v1/notes/list

Generate API keys from the OpenWhispr desktop app: open Integrations in the left sidebar and use the API card. Keys start with owk_live_ and are shown once at creation. API key management is offered on paid plans.

Two exceptions: the agent bootstrap endpoints (/auth/email-code, /auth/email-code/verify) take no credentials at all — that’s how an assistant gets its first token. And the /keys/* management endpoints also accept the short-lived session token (owt_) that bootstrap produces, not just an owk_live_ API key. Every other endpoint needs a Bearer owk_live_ (or ow_wks_live_) key.

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. Read note transcripts. List folders.
`notes:write`	Create, update, and delete notes. Create folders.
`transcriptions:read`	List and get transcription history.
`transcriptions:delete`	Delete a transcription and its audio. Not offered in the desktop app — create the key via the API.
`usage:read`	Read usage statistics. Granted to every key automatically.

Keys that start with ow_wks_live_ are workspace keys and carry a different set of scopes — see Workspace API keys.

Response format

All responses use a consistent envelope.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Meeting notes",
    "content": "Discussed the roadmap..."
  }
}

{
  "data": [
    { "id": "...", "title": "Note 1" },
    { "id": "...", "title": "Note 2" }
  ],
  "has_more": true,
  "next_cursor": "$NEXT_CURSOR"
}

{
  "error": {
    "code": "not_found",
    "message": "Note not found"
  }
}

Pagination

List endpoints use cursor-based pagination. Treat next_cursor as an opaque token — pass it back exactly as received via the cursor query parameter; never parse or construct one yourself.

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

# Next page — $NEXT_CURSOR is the next_cursor value from the previous response
curl -H "Authorization: Bearer $KEY" \
  "https://api.openwhispr.com/api/v1/notes/list?limit=50&cursor=$NEXT_CURSOR"

When has_more is false, you’ve reached the end.

Rate limits

Limits are per API key with minute and daily windows. A search request counts as 5 against both windows.

Plan	Per minute	Per day
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`)

Overview

CLI

Integrations

Open source

Base URL

Authentication

Scopes

Response format

Rate limits

​Base URL

​Authentication

​Scopes

​Response format

​Pagination

​Rate limits

Base URL

Authentication

Scopes

Response format

Pagination

Rate limits