OpenParable
Skip to content
← Back to skills

Openwhispr API

Apps & Automation
openwhispr-api

Openwhispr API is an Agent Skill for apps & automation published in the OpenWhispr/openwhispr repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use this skill when building integrations with the OpenWhispr REST API, calling OpenWhispr endpoints, managing notes/folders/transcriptions programmatically, or connecting to the OpenWhispr MCP server. Covers authentication, all V1 endpoints, pagination, rate limits, error handling, and the remote MCP server.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/OpenWhispr/openwhispr/blob/HEAD/agent-skills/openwhispr-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/openwhispr-api, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

OpenWhispr API v1

Use this reference when making requests to the OpenWhispr REST API. All endpoints are under the V1 path and require API key authentication.

Authentication

Pass the API key as a Bearer token in the Authorization header on every request.

Authorization: Bearer owk_live_YOUR_KEY

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

Scopes

Each key has scoped permissions. The API rejects requests missing the required scope with 403 Forbidden.

ScopeGrants
notes:readList, get, and search notes. List folders.
notes:writeCreate, update, and delete notes. Create folders.
transcriptions:readList and get transcriptions.
usage:readRead usage statistics.

Base URL

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

Response Envelope

Wrap all responses in a consistent envelope.

Single resource:

{ "data": { "id": "uuid", "title": "My note", ... } }

Paginated list:

{
  "data": [{ ... }, { ... }],
  "has_more": true,
  "next_cursor": "2026-04-15T10:30:00.000Z"
}

Error:

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

Error Codes

HTTP StatusCodeMeaning
400validation_errorInvalid request body or query params
401invalid_api_keyMissing, malformed, expired, or revoked key
403forbiddenKey lacks required scope
404not_foundResource does not exist or belongs to another user
405method_not_allowedWrong HTTP method
409conflictDuplicate resource (e.g. folder name)
429rate_limitedRate limit exceeded — check Retry-After header
500internal_errorServer error

Rate Limits

Enforced per API key with minute and daily windows. Search requests cost 5x against the rate limit.

PlanPer MinutePer Day
Free301,000
Pro12010,000
Business30050,000

Response headers on every request:

HeaderDescription
X-RateLimit-LimitMax requests per minute
X-RateLimit-RemainingRemaining in current window
X-RateLimit-ResetUnix timestamp when window resets
Retry-AfterSeconds to wait (only on 429)

Pagination

List endpoints use cursor-based pagination. Pass the next_cursor value from a previous response as the cursor query parameter to fetch the next page. When has_more is false, there are no more results.

GET /notes/list?limit=50&cursor=2026-04-15T10:30:00.000Z

Endpoints

Notes

List Notes — GET /notes/list

ParamTypeRequiredDescription
limitintegerNo1-100, default 50
cursorstringNoPagination cursor
folder_idUUIDNoFilter by folder
Scope: notes:read

Get Note — GET /notes/{id} Scope: notes:read. Returns 404 if the note does not exist or is deleted.

Create Note — POST /notes/create

FieldTypeRequiredDescription
contentstringYesNote body text
titlestringNoNote title
enhanced_contentstringNoCleaned/enhanced version
note_typeenumNopersonal (default), meeting, upload
folder_idUUIDNoTarget folder
Scope: notes:write. Returns 201 with the created note.

Update Note — PATCH /notes/{id}

FieldTypeRequiredDescription
titlestringNoNew title
contentstringNoNew content
enhanced_contentstringNoNew enhanced content
folder_idUUIDNoMove to folder
Scope: notes:write. All fields optional — only provided fields are updated.

Delete Note — DELETE /notes/{id} Scope: notes:write. Soft-deletes the note. Returns 204 No Content.

Search Notes — POST /notes/search

FieldTypeRequiredDescription
querystringYesSearch text (1-500 chars)
limitintegerNo1-50, default 20
Scope: notes:read. Uses hybrid semantic (vector) + full-text search with relevance scoring. Costs 5x against rate limit.

Folders

List Folders — GET /folders/list Scope: notes:read. Returns all folders sorted by sort_order then created_at.

Create Folder — POST /folders/create

FieldTypeRequiredDescription
namestringYesFolder name (1-100 chars)
sort_orderintegerNoSort position
Scope: notes:write. Max 50 folders per user. Returns 409 if name already exists.

Transcriptions

List Transcriptions — GET /transcriptions/list

ParamTypeRequiredDescription
limitintegerNo1-100, default 50
cursorstringNoPagination cursor
Scope: transcriptions:read. Returns transcription history with text, word_count, source, provider, model, language, audio_duration_ms, processing_ms.

Get Transcription — GET /transcriptions/{id} Scope: transcriptions:read.

Usage

Get Usage — GET /usage Scope: usage:read. Returns:

  • words_used — Words consumed this period
  • words_remaining — Words left in quota
  • limit — Total word quota
  • plan — Current plan (free, pro, business)
  • is_subscribed — Whether user has active subscription
  • current_period_end — End of current billing period
  • billing_interval — Billing cycle

MCP Server

For AI assistant integration (Claude, Cursor, VS Code), connect to the remote MCP server at:

https://mcp.openwhispr.com/mcp

Pass the API key via Authorization: Bearer header. All V1 endpoints are available as MCP tools. The server uses Streamable HTTP transport (stateless, no sessions).

Claude Code

claude mcp add openwhispr --transport http https://mcp.openwhispr.com/mcp \
  --header "Authorization: Bearer owk_live_YOUR_KEY"

Cursor / VS Code

{
  "mcpServers": {
    "openwhispr": {
      "url": "https://mcp.openwhispr.com/mcp",
      "headers": { "Authorization": "Bearer owk_live_YOUR_KEY" }
    }
  }
}

Examples

List recent notes

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

Create a note in a folder

curl -X POST \
  -H "Authorization: Bearer owk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Remember to review PR #42", "title": "TODO", "folder_id": "UUID"}' \
  https://api.openwhispr.com/api/v1/notes/create

Search notes

curl -X POST \
  -H "Authorization: Bearer owk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "quarterly budget discussion"}' \
  https://api.openwhispr.com/api/v1/notes/search

Paginate through all notes

cursor=""
while true; do
  response=$(curl -s -H "Authorization: Bearer owk_live_YOUR_KEY" \
    "https://api.openwhispr.com/api/v1/notes/list?limit=100&cursor=${cursor}")
  echo "$response" | jq '.data[]'
  has_more=$(echo "$response" | jq -r '.has_more')
  [ "$has_more" != "true" ] && break
  cursor=$(echo "$response" | jq -r '.next_cursor')
done

Check usage

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