API overview - OpenWhispr

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.

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.

{
  "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": "2026-04-15T10:30:00.000Z"
}

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

Pagination

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

# 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`)

​Base URL

​Authentication

​Scopes

​Response format

​Pagination

​Rate limits