API Reference¶

Speakr provides a comprehensive REST API (v1) for automation tools, dashboard widgets, and custom integrations. This reference documents all available endpoints.

Base URL¶

All API v1 endpoints are prefixed with /api/v1:

https://your-speakr-instance.com/api/v1/

Authentication¶

All endpoints require authentication, except the API description and the interactive API docs. See API Tokens for details on creating and managing tokens.

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://speakr.example.com/api/v1/stats

curl -H "X-API-Token: YOUR_TOKEN" \
     https://speakr.example.com/api/v1/stats

curl "https://speakr.example.com/api/v1/stats?token=YOUR_TOKEN"

A header is the preferred way to send a token. The ?token= query parameter is deprecated and is accepted only on GET requests, and only with full-access tokens. A POST, PUT, PATCH or DELETE request that carries the token only in ?token= gets 401 with the code query_token_read_only. Every response to a request that uses ?token= carries the header Deprecation: true. A URL that contains a token can be recorded in proxy logs and browser history, so a header is the safer choice for every client.

Scopes¶

A token has full access or a set of scopes. Each endpoint below lists the scope it needs; /api/v1/openapi.json gives the same as x-required-scopes per operation.

A token with no scopes is a full-access token and is reported as ["full"]. Every token created before scopes existed is a full-access token. Scoped tokens work only in a header and only on API v1 routes. A scoped token without a needed scope gets 403 before anything changes:

{
  "error": "This token does not have the 'write' scope",
  "code": "insufficient_scope",
  "required_scopes": ["write"],
  "token_scopes": ["read"]
}

with the header WWW-Authenticate: Bearer error="insufficient_scope", scope="write".

Current Token¶

GET /api/v1/tokens/current

Scope: none (any valid token)

Returns the token used for the request. A request signed in through the web interface gets 404 with "code": "not_found".

{
  "id": 14,
  "name": "mailr",
  "scopes": ["read", "write", "upload"],
  "created_at": "2026-10-02T09:00:00.000000Z",
  "expires_at": "2027-10-02T09:00:00.000000Z",
  "last_used_at": "2026-10-02T09:05:11.000000Z",
  "via": "header"
}

Capabilities¶

GET /api/v1/capabilities

Scope: none (any valid token or a signed-in session)

Lists the features this instance supports. Read features here, not from the version string; a feature missing from features is not supported.

{
  "speakr_version": "v0.10.11-alpha",
  "api_version": "1.1",
  "features": {"token_scopes": true, "changes_feed": true, "etags": true},
  "models_local": false
}

models_local is true only when the administrator sets MODELS_ARE_LOCAL=true, which states that the text, chat and embedding models all run on machines the administrator controls.

OpenAPI Specification¶

Both addresses are available without signing in, by design. They describe the endpoints only and contain no user data or credentials.

Every operation in the specification has an operationId, which is required to add Speakr to Open WebUI as an OpenAPI tool server. When the specification is fetched with a scoped token, it lists only the operations that token may call, so a tool server built from it offers only those tools. A full token or a signed-in browser session receives every operation.

Interactive API documentation with Swagger UI at /api/v1/docs

Stats¶

Dashboard-compatible statistics endpoint, designed for integration with homepage widgets like gethomepage.dev.

Get Statistics¶

GET /api/v1/stats

Scope: read

Query Parameters:

Response:

{
  "recordings": {
    "total": 150,
    "completed": 120,
    "processing": 5,
    "pending": 20,
    "failed": 5
  },
  "storage": {
    "used_bytes": 5368709120,
    "used_human": "5.0 GB"
  },
  "queue": {
    "jobs_queued": 3,
    "jobs_processing": 1
  },
  "tokens": {
    "used_this_month": 450000,
    "budget": 1000000,
    "percentage": 45.0
  },
  "transcription": {
    "used_this_month_seconds": 3600,
    "used_this_month_minutes": 60,
    "budget_seconds": 36000,
    "budget_minutes": 600,
    "percentage": 10.0,
    "estimated_cost": 0.36
  },
  "activity": {
    "recordings_today": 3,
    "last_transcription": "2024-01-15T14:30:00Z"
  }
}

- Speakr:
    widget:
      type: customapi
      url: https://speakr.example.com/api/v1/stats
      headers:
        Authorization: Bearer YOUR_TOKEN
      mappings:
        - field: recordings.completed
          label: Completed
        - field: storage.used_human
          label: Storage
        - field: tokens.percentage
          label: Token Usage
          format: percent
        - field: transcription.percentage
          label: Transcription
          format: percent
        - field: activity.recordings_today
          label: Today

Current User¶

Get Current User¶

GET /api/v1/users/me

Scope: read

Returns the authenticated user's profile, preferences, and group memberships. Useful for companion apps and automation flows that need to display the current user's identity.

Response:

{
  "id": 42,
  "username": "alice",
  "email": "alice@example.com",
  "name": "Alice Johnson",
  "job_title": "Product Manager",
  "company": "Acme Inc",
  "is_admin": false,
  "email_verified": true,
  "sso_provider": null,
  "can_share_publicly": true,
  "preferences": {
    "ui_language": "en",
    "transcription_language": "en",
    "output_language": "en",
    "extract_events": true,
    "auto_speaker_labelling": true,
    "auto_speaker_labelling_threshold": 0.75,
    "auto_summarization": true,
    "show_timestamps_simple_view": false,
    "editor_autosave": true,
    "auto_translation": false,
    "diarize": true
  },
  "group_memberships": [
    {
      "group_id": 3,
      "group_name": "Engineering",
      "role": "admin",
      "joined_at": "2024-01-10T08:00:00Z"
    }
  ],
  "storage": {
    "used_bytes": 244862976,
    "quota_bytes": 314572800,
    "available_bytes": 69709824
  }
}

storage.quota_bytes and storage.available_bytes are null when the user has no storage quota.

Recordings¶

Upload Recording¶

POST /api/v1/recordings/upload

Scope: upload

Upload a recording as multipart form-data and immediately queue transcription.

Form Fields:

The meeting date is chosen in this order: meeting_date, a date in the file name (when you turned that on in your settings), file_last_modified, the date stored in the file, the upload time.

Idempotent uploads. Send an idempotency_key (for example a message id and attachment number) when a client may retry. A repeat with the same key by the same user within 24 hours returns the recording the first call created, with 200 and "idempotent_replay": true; the file is not stored again and no second transcription is queued. Keys are per user.

Response:

// 202 Accepted
{
  "id": 123,
  "title": "Weekly sync",
  "status": "PENDING",
  "created_at": "2024-01-15T10:00:00Z",
  "meeting_date": "2024-01-15T09:00:00Z",
  "participants": "Dana, Omar",
  "file_size": 15728640,
  "original_filename": "meeting.mp3",
  "mime_type": "audio/mpeg",
  "notes": "Quick test upload",
  "external_refs": [{"id": 77, "system": "mailr", "kind": "event", "ref": "5f1c@example.com", "url": null, "label": null, "created_at": "2024-01-15T10:00:00.000000Z"}],
  "ignored": {"tag_ids": [], "folder_id": null}
}

ignored lists the tags and folder the upload dropped because you cannot use them.

An upload that would exceed the user's storage quota is refused with 507 Insufficient Storage:

{
  "error": "This upload would exceed your storage quota: 233.5 MB of 300.0 MB used, and the file is 80.0 MB.",
  "code": "storage_quota_exceeded",
  "used_bytes": 244862976,
  "quota_bytes": 314572800,
  "file_bytes": 83886080,
  "available_bytes": 69709824
}

GET /api/v1/users/me includes the same figures under storage, and /api/v1/capabilities lists storage_quota.

A file that cannot be ingested is refused with 400. No recording is created and the file is not kept:

{
  "error": "The uploaded file could not be read as audio. It may be corrupt or in an unsupported format.",
  "code": "audio_decode_failed"
}

A conversion that runs longer than FFMPEG_TIMEOUT_SECONDS is a server error: 500 with the code audio_conversion_timeout.

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/audio.mp3" \
  -F "title=Weekly sync" \
  -F "participants=Dana, Omar" \
  -F 'external_refs=[{"system":"mailr","kind":"event","ref":"5f1c@example.com"}]' \
  -F "idempotency_key=msg-4411:part-2" \
  https://speakr.example.com/api/v1/recordings/upload

ASR Voice Recorder Upload¶

POST /api/v1/integrations/asr-voice-recorder/upload

Scope: upload

This adapter accepts the multipart webhook format sent by the Android ASR Voice Recorder app and queues the completed recording through Speakr's normal upload and transcription pipeline. Unlike other API endpoints, authentication comes from the required multipart secret field because the recorder cannot set a custom Authorization header.

Form Fields:

A session cookie or normal API Authorization header does not replace secret on this endpoint. Create a dedicated, expiring token for the recorder because Speakr API tokens currently provide full access to their owner's account. The endpoint limits each source IP by both request count and total declared upload size; HTTP 429 means ASR should retry later. Multi-worker deployments using Flask-Limiter's in-memory storage should also enforce an aggregate upload rate at the reverse proxy.

When saving the webhook destination, ASR first sends an authenticated connection test without a file or recording metadata. Speakr returns HTTP 200 with {"status":"ok","connection_test":true} and does not create a recording. Completed deliveries still require the file field.

Response:

// 200 OK
{
  "id": 123,
  "title": "Recording - interview.m4a",
  "status": "PENDING",
  "original_filename": "interview.m4a",
  "notes": "Interview recorded with an external microphone",
  "idempotent_replay": false
}

An empty or undecodable file is refused with 400 and the codes empty_file or audio_decode_failed, as on Upload Recording.

If ASR retries the same completed file with matching filename, note, and recording date for the same user, Speakr returns the existing recording with idempotent_replay: true instead of queueing another transcription. Identical audio submitted with different metadata remains a distinct recording. Simultaneous first deliveries are not a strict exactly-once guarantee.

ASR Voice Recorder configuration:

• Webhook URL: https://speakr.example.com/api/v1/integrations/asr-voice-recorder/upload
• Secret: the dedicated Speakr API token
• Method/body: ASR supplies the multipart POST automatically
• Expected success status: HTTP 200

A manual protocol check can be made with placeholder credentials:

curl -X POST \
  -F "secret=YOUR_DEDICATED_TOKEN" \
  -F "file=@recording.m4a" \
  -F "file_name=recording.m4a" \
  -F "note=Mobile recorder upload" \
  https://speakr.example.com/api/v1/integrations/asr-voice-recorder/upload

List Recordings¶

GET /api/v1/recordings

Scope: read

Query Parameters:

Response:

{
  "recordings": [
    {
      "id": 123,
      "title": "Team Meeting",
      "status": "COMPLETED",
      "created_at": "2024-01-15T10:00:00Z",
      "completed_at": "2024-01-15T10:05:00Z",
      "meeting_date": "2024-01-15T09:00:00Z",
      "file_size": 15728640,
      "original_filename": "meeting.mp3",
      "participants": "Alice, Bob",
      "is_inbox": false,
      "is_highlighted": true,
      "audio_available": true,
      "audio_duration": 1830.5,
      "has_transcription": true,
      "has_summary": true,
      "processing_time_seconds": 45.2,
      "transcription_duration_seconds": 38.1,
      "summarization_duration_seconds": 7.1,
      "folder_id": 5,
      "folder": {"id": 5, "name": "Client Calls"},
      "deletion_exempt": false,
      "error_message": null,
      "keep_audio_only": false,
      "tags": [
        {"id": 1, "name": "Work", "color": "#3B82F6"}
      ],
      "updated_at": "2024-01-15T10:05:00.000000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  }
}

Shared recordings. With scope=shared or scope=all the list includes completed recordings other users shared with you (shared directly, through a group tag or through a group folder), as the web app's shared list does. Every item says whose it is:

{
  "is_shared": true,
  "owner": {"id": 3, "username": "evan", "name": "Evan Ross"},
  "share": {"id": 51, "can_edit": false, "can_reshare": false, "source": "group_tag",
            "shared_at": "2026-09-20T10:00:00.000000Z"}
}

Your own recordings have "is_shared": false, "owner": null, "share": null. owner.username and owner.name are null unless the administrator sets SHOW_USERNAMES_IN_UI=true. For a shared recording, is_inbox, is_highlighted and is_archived are your own values and tags are the tags you can see. With internal sharing turned off, shared is empty and all is the same as own.

updated_at is the time of the last change a client can see: title, participants, notes, summary, transcript, status, dates, folder, flags, tags, events or sharing. It is present on every recording in API v1 and starts at created_at.

External References¶

A reference links a recording to an item in another system, such as a calendar event or a conversation in a mail client. References are private: you see only the ones you added, and a user a recording is shared with sees only their own. Every recording in the API carries your references in external_refs.

{
  "id": 77,
  "system": "mailr",
  "kind": "event",
  "ref": "5f1c@example.com@2026-10-06T15:00:00Z",
  "url": "https://mail.example.com/calendar/event/5f1c",
  "label": "Weekly sync (6 Oct)",
  "created_at": "2026-10-06T16:02:11.000000Z"
}

system and kind: 1 to 40 characters of a-z, 0-9, _, ., -. ref: 1 to 500 printable characters. url: optional, http:// or https://, at most 1000 characters. label: optional, at most 200 characters. At most 50 references per user per recording (409 conflict).

GET /api/v1/recordings/{id}/external-refs

Scope: read

POST /api/v1/recordings/{id}/external-refs

Scope: write

Adds one reference: 201 with the new reference, or 200 with the existing one when you already added the same system, kind and ref.

PUT /api/v1/recordings/{id}/external-refs?system=mailr

Scope: write

Replaces your references of that system with {"external_refs": [...]} and returns the new list. References of other systems stay.

DELETE /api/v1/recordings/{id}/external-refs/{ref_id}

Scope: write

204. The writes need edit access to the recording, and a reference change counts as a recording change (updated_at, fields_changed: ["external_refs"]).

To find recordings by reference, filter the list: GET /api/v1/recordings?external_system=mailr&external_ref=<ref>, optionally with &external_kind=event.

Changes Feed¶

GET /api/v1/recordings/changes

Scope: read

Every create, edit and delete of your recordings since a cursor, each once and in its latest state. This is the way to keep a copy of your recordings in sync without listing the whole collection.

Response:

{
  "changes": [
    {"type": "upsert", "recording": {"id": 412, "title": "Weekly sync", "updated_at": "2026-10-02T14:03:22.123456Z"}},
    {"type": "delete", "id": 398, "deleted_at": "2026-10-02T14:05:00.000000Z", "reason": "deleted"}
  ],
  "next_cursor": "eyJ1IjoiMjAyNi0xMC0wMlQxNDowNTowMC4wMDAwMDBaIiwiayI6MSwiaSI6Mzk4fQ",
  "has_more": false
}

• recording in an upsert has the same fields as one item of List Recordings.
• reason on a delete is deleted (by a user, the API or a merge), retention (auto-deletion) or access_revoked (a recording shared with you is no longer shared).
• Changes from the last two seconds wait for the next call, so a change saved late is never skipped.
• The cursor is opaque. Store next_cursor after every answer, including an answer with no changes.
• 400 with "code": "invalid_parameter": the cursor cannot be read.
• 410 with "code": "cursor_expired": the cursor is older than the deletions Speakr still keeps (RECORDING_TOMBSTONE_DAYS, default 90). Start again without a cursor.

A sync loop:

cursor = stored cursor, or none
repeat:
    answer = GET /api/v1/recordings/changes?cursor=<cursor>
    if status is 410: drop the local copy's sync state, cursor = none, continue
    apply each change: upsert replaces the recording, delete removes it
    cursor = answer.next_cursor; store it
    if not answer.has_more: wait (or wait for a webhook), then repeat

Conditional Requests¶

These requests send a weak ETag header:

Send the value back in If-None-Match. When nothing in the answer changed, the answer is 304 Not Modified with no body. Treat the value as opaque. The access check comes first, so a caller without access gets 404, never 304. The answers carry Cache-Control: private, no-cache.

curl -i -H "Authorization: Bearer $TOKEN" -H 'If-None-Match: W/"t412-1790950000000000-3f2a9c0d1b7e4a55"' \
     https://speakr.example.com/api/v1/recordings/412/transcript

Get Recording Details¶

GET /api/v1/recordings/{id}

Scope: read

Query Parameters:

Response:

{
  "id": 123,
  "title": "Team Meeting",
  "status": "COMPLETED",
  "participants": "Alice, Bob",
  "created_at": "2024-01-15T10:00:00Z",
  "meeting_date": "2024-01-15T09:00:00Z",
  "completed_at": "2024-01-15T10:05:00Z",
  "file_size": 15728640,
  "original_filename": "meeting.mp3",
  "mime_type": "audio/mpeg",
  "is_inbox": false,
  "is_highlighted": true,
  "audio_available": true,
  "audio_duration": 1830.5,
  "processing_time_seconds": 45.2,
  "transcription_duration_seconds": 38.1,
  "summarization_duration_seconds": 7.1,
  "folder_id": 5,
  "folder": {"id": 5, "name": "Client Calls"},
  "deletion_exempt": false,
  "events": [
    {
      "id": 1,
      "title": "Follow-up Meeting",
      "start_datetime": "2024-01-22T10:00:00Z",
      "end_datetime": "2024-01-22T11:00:00Z",
      "description": "Discuss project progress",
      "location": "Conference Room A"
    }
  ],
  "error_message": null,
  "duplicate_info": null,
  "keep_audio_only": false,
  "transcription": "Alice: Hello everyone...",
  "summary": "## Meeting Summary\n- Key point 1...",
  "notes": "Personal notes..."
}

Get Transcript¶

GET /api/v1/recordings/{id}/transcript

Scope: read

Query Parameters:

{
  "format": "json",
  "kind": "segments",
  "duration": 1834.2,
  "segments": [
    {
      "index": 0,
      "speaker": "Alice",
      "speaker_label": "SPEAKER_00",
      "speaker_id": 12,
      "text": "Hello everyone",
      "sentence": "Hello everyone",
      "start_time": 0.0,
      "end_time": 2.5
    }
  ]
}

{
  "format": "text",
  "content": "Alice: Hello everyone\n\nBob: Hi Alice..."
}

{
  "format": "srt",
  "content": "1\n00:00:00,000 --> 00:00:02,500\nHello everyone\n\n2\n..."
}

{
  "format": "vtt",
  "content": "WEBVTT\n\n00:00:00.000 --> 00:00:02.500\n<v Alice>Hello everyone\n\n..."
}

Get Summary¶

GET /api/v1/recordings/{id}/summary

Scope: read

Response:

{
  "summary": "## Meeting Summary\n\n### Key Points\n- Point 1...",
  "has_summary": true
}

Get Notes¶

GET /api/v1/recordings/{id}/notes

Scope: read

Notes are per user. The owner gets the recording's notes. A user the recording is shared with gets only their own personal notes, never the owner's; the same holds for notes in the recording details and in search.

Response:

{
  "notes": "My personal notes about this meeting...",
  "has_notes": true
}

Get Processing Status¶

GET /api/v1/recordings/{id}/status

Scope: read

Response:

{
  "id": 123,
  "status": "PROCESSING",
  "queue_position": 2,
  "error_message": null,
  "completed_at": null
}

Status Values:

Update Recording¶

PATCH /api/v1/recordings/{id}

Scope: write

Request Body:

{
  "title": "Updated Title",
  "participants": "Alice, Bob, Charlie",
  "notes": "Updated notes...",
  "summary": "Updated summary...",
  "meeting_date": "2024-01-15T09:00:00Z",
  "is_inbox": false,
  "is_highlighted": true,
  "is_archived": false,
  "folder_id": 5
}

All fields are optional. Set folder_id to an integer to move the recording into that folder (you must have access to the target folder), or to null to remove it from any folder. folder_id requires folders to be enabled.

Replace Notes¶

PUT /api/v1/recordings/{id}/notes

Scope: write

The owner replaces the recording's notes. A user the recording is shared with, even with view access only, replaces their own personal notes; the owner's notes do not change. notes in PATCH /api/v1/recordings/{id} follows the same rule.

Request Body:

{
  "notes": "New notes content..."
}

Replace Summary¶

PUT /api/v1/recordings/{id}/summary

Scope: write

Request Body:

{
  "summary": "## New Summary\n- Point 1..."
}

Delete Audio, Keep Transcript¶

POST /api/v1/recordings/{id}/delete-audio

Scope: delete

Deletes the recording's media file (the video, for a recording with retained video) and keeps the transcript, summary and notes. Requires the same permission as deleting the recording. Returns 409 when the audio is already removed or the recording is still processing.

Response:

{
  "success": true,
  "audio_deleted_at": "2026-09-29T06:50:17.968177"
}

Delete Recording¶

DELETE /api/v1/recordings/{id}

Scope: delete

Response:

{
  "success": true,
  "message": "Recording deleted"
}

Share Links¶

Create or Reuse a Share Link¶

POST /api/v1/recordings/{id}/share

Scope: share

Only the recording's owner can create a link. Without force_new, the newest link of the recording is reused.

{"share_summary": true, "share_notes": false, "force_new": false, "update_existing": false, "expires_in_days": 30}

201 for a new link, 200 for a reused one:

{
  "share_url": "https://speakr.example.com/share/AbC123",
  "existing": true,
  "flags_differ": false,
  "share": {"id": 31, "share_summary": true, "share_notes": false,
            "created_at": "2026-10-02T09:00:00.000000Z", "expires_at": null}
}

403 with code feature_disabled (public sharing is off), not_permitted (your account may not create public links) or https_required (the link would not be an HTTPS link: when APP_BASE_URL is set, its scheme decides and links use that address; otherwise the request must arrive over HTTPS, and behind a reverse proxy Speakr reads X-Forwarded-Proto, see TRUSTED_PROXY_HOPS and TRUSTED_PROXIES).

List Share Links¶

GET /api/v1/recordings/{id}/shares

Scope: share

Your links of the recording, newest first, each with its share_url.

Revoke a Share Link¶

DELETE /api/v1/shares/{share_id}

Scope: share

204. The link stops working at once.

Search¶

Search Recordings¶

GET /api/v1/search

Scope: read

Finds words in the titles, participants, notes, summaries and transcripts of your recordings, with the time and speaker of each transcript hit. Keyword search works on every installation; semantic search needs Inquire mode.

Response:

{
  "query": "budget freeze",
  "mode_used": "keyword",
  "results": [
    {
      "recording_id": 412,
      "title": "Weekly sync",
      "meeting_date": "2026-09-29T15:00:00Z",
      "field": "transcript",
      "segment_index": 87,
      "start_time": 754.2,
      "end_time": 761.0,
      "speaker": "Dana",
      "text": "So the budget freeze applies to travel only.",
      "match_spans": [[7, 13], [14, 20]],
      "score": 0.7
    }
  ],
  "page": 1,
  "has_more": false
}

• Keyword hits: the title and participants as a whole, notes and summaries per line, transcripts per segment. text is at most 400 characters around the first match; match_spans are character offsets into text. A transcript without speaker segments gives hits with start_time and segment_index set to null.
• score is the share of the query words in the hit times a weight per field (title 1.0, summary 0.9, notes and participants 0.8, transcript 0.7). Ties go to the newer recording.
• Keyword mode reads at most the 200 newest matching recordings per request.
• Semantic hits come from the Inquire index: field is transcript, segment_index is null, score is the similarity. The query text is sent to the embedding model of the instance; GET /api/v1/capabilities reports features.search.semantic and models_local.
• mode=semantic on an instance without Inquire mode: 409 with "code": "semantic_unavailable".
• Limit: 30 requests per minute per token (API_SEARCH_RATE_LIMIT).

Tags¶

List Tags¶

GET /api/v1/tags

Scope: read

Returns both personal tags and group tags you have access to. ?name= returns only the tag with that name (any case), so a client can find a tag by name.

Response:

{
  "tags": [
    {
      "id": 1,
      "name": "Work Meetings",
      "color": "#3B82F6",
      "is_group_tag": false,
      "group_id": null,
      "custom_prompt": "Focus on action items...",
      "default_language": "en",
      "default_min_speakers": 2,
      "default_max_speakers": 10,
      "protect_from_deletion": false,
      "can_edit": true
    }
  ]
}

Create Tag¶

POST /api/v1/tags

Scope: write

Request Body:

{
  "name": "Interviews",
  "color": "#10B981",
  "custom_prompt": "Extract candidate qualifications...",
  "default_language": "en",
  "default_min_speakers": 2,
  "default_max_speakers": 3,
  "group_id": null
}

Update Tag¶

PUT /api/v1/tags/{id}

Scope: write

Request Body:

{
  "name": "Updated Name",
  "color": "#EF4444",
  "custom_prompt": "New prompt..."
}

Delete Tag¶

DELETE /api/v1/tags/{id}

Scope: delete

Add Tags to Recording¶

POST /api/v1/recordings/{id}/tags

Scope: write

Request Body:

{
  "tag_ids": [1, 2, 3]
}

Adds the tags after the ones already on the recording. Needs edit access to the recording. A group tag can be applied by the recording's owner or a group admin.

Tags that share. A group tag with auto-share on apply (or share with group lead) shares a completed recording with the group, as in the web app: admins get edit access, members read access. A scoped token needs the share scope for such a tag; without it the request gets 403 insufficient_scope and nothing changes.

Set Recording Tags¶

PUT /api/v1/recordings/{id}/tags

Scope: write

Sets the recording's tags to exactly this list, in this order. The access and sharing rules of Add Tags apply. Tags of other users that you cannot see stay on the recording.

{"tag_ids": [3, 9]}

Response:

{
  "tags": [{"id": 3, "name": "Followed up", "color": "#10B981"}, {"id": 9, "name": "Client", "color": "#3B82F6"}],
  "added": [9],
  "removed": [4]
}

An unknown tag, or one you cannot use, gives 400 with "code": "invalid_parameter" and the refused ids in tag_ids; nothing changes.

Remove Tag from Recording¶

DELETE /api/v1/recordings/{id}/tags/{tag_id}

Scope: write

Speakers¶

List Speakers¶

GET /api/v1/speakers

Scope: read

?email= returns the speaker with that address (any case).

Response:

{
  "speakers": [
    {
      "id": 1,
      "name": "John Doe",
      "use_count": 45,
      "last_used": "2024-01-15T14:30:00Z",
      "confidence_score": 0.87,
      "has_voice_profile": true,
      "email": "john@example.com",
      "aliases": ["Johnny"],
      "updated_at": "2024-01-15T14:30:00.000000Z"
    }
  ]
}

email and aliases are contact details you give your speakers. Only you see them: they are not part of shared recordings, public shares, exports or webhooks, and they are deleted with the speaker.

Create Speaker¶

POST /api/v1/speakers

Scope: write

Request Body:

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "aliases": ["J. Smith"]
}

email and aliases are optional.

Update Speaker¶

PUT /api/v1/speakers/{id}

Scope: write

Changes the name, email or aliases; send only what changes. A new name appears in every recording the speaker is in (transcript, participants, search). email must be an address (stored in lower case); null or "" removes it. aliases: at most 20 names of at most 100 characters, trimmed, duplicates (any case) dropped; [] removes them. A name another of your speakers has gives 409.

Request Body:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "aliases": ["J. Doe"]
}

Delete Speaker¶

DELETE /api/v1/speakers/{id}

Scope: delete

Get Recording Speakers¶

GET /api/v1/recordings/{id}/speakers

Scope: read

Returns the people in the recording with voice-based identification suggestions. Each entry is one person: the diarization label, the name given to it (null while unnamed), the saved speaker it is linked to, and email when you own both the recording and the speaker (null for anyone else).

Response:

{
  "speakers": [
    {
      "label": "SPEAKER_00",
      "identified_name": "John Doe",
      "speaker_id": 1,
      "email": "john@example.com",
      "segment_count": 23
    }
  ],
  "suggestions": {
    "SPEAKER_01": [
      {"speaker_id": 2, "name": "Jane Smith", "similarity": 89.5}
    ]
  }
}

Processing Operations¶

Queue Transcription¶

POST /api/v1/recordings/{id}/transcribe

Scope: process

Request Body:

{
  "language": "en",
  "min_speakers": 1,
  "max_speakers": 5,
  "hotwords": "Speakr, WhisperX, diarization",
  "initial_prompt": "Technical discussion about audio transcription.",
  "transcription_model": "gpt-4o-transcribe-diarize"
}

All parameters are optional.

Response:

{
  "success": true,
  "job_id": "abc123",
  "status": "QUEUED",
  "message": "Transcription queued"
}

Queue Summarization¶

POST /api/v1/recordings/{id}/summarize

Scope: process

Request Body:

{
  "custom_prompt": "Focus on technical decisions and action items only"
}

The custom prompt overrides the recording's tag prompts and user defaults.

Chat¶

Chat with Recording¶

POST /api/v1/recordings/{id}/chat

Scope: process

Ask questions about a recording's content using AI.

Request Body:

{
  "message": "What were the main action items discussed?",
  "conversation_history": [
    {"role": "user", "content": "Who attended?"},
    {"role": "assistant", "content": "John and Jane attended..."}
  ]
}

Response:

{
  "response": "The main action items were:\n1. Complete the report by Friday\n2. Schedule follow-up meeting...",
  "sources": []
}

Sources. With "with_sources": true, the transcript goes to the model with segment markers and the answer cites segments with short quotes. Citations in response become [1], [2], and sources lists them:

{
  "response": "The freeze covers travel only [1].",
  "sources": [{"n": 1, "segment_index": 12, "start_time": 754.2, "end_time": 761.0,
               "speaker": "Dana", "quote": "the budget freeze applies to travel only", "verified": true}]
}

verified is true when the quote appears in that segment (ignoring case and spacing). A citation of a segment that does not exist has segment_index: null and verified: false.

The notes in the chat context are the ones you can see: your own for your recordings, your personal notes for a recording shared with you. Chat sends the transcript to the chat model of the instance; GET /api/v1/capabilities reports models_local.

Inquire¶

Ask Across Recordings¶

POST /api/v1/inquire

Scope: process

Answers a question from the recordings you can read, with Inquire's search (and the Inquire agent when the administrator turned it on). Needs Inquire mode on the instance (403 feature_disabled otherwise).

{
  "question": "What did we decide about the course redesign?",
  "filters": {"recording_ids": [412, 398], "tag_ids": [], "folder_ids": [], "speakers": [], "date_from": "2026-09-01", "date_to": null},
  "scope": "own",
  "mode": "auto",
  "stream": false,
  "history": []
}

• mode: rag, agent (403 feature_disabled when the agent is off) or auto (the agent when it is on).
• scope: own, shared or all, as on List Recordings.
• stream: true returns the server-sent events of the web app's Inquire (delta, status, agent_step, agent_summary, error).

Response (stream: false):

{
  "answer": "The redesign moves the project to week 6 [1] and drops the midterm [2].",
  "citations": [
    {"n": 1, "recording_id": 412, "title": "Weekly sync", "start_time": 754, "quote": null,
     "url": "/recordings/412?t=754"},
    {"n": 2, "recording_id": 398, "title": "Budget review", "start_time": null, "quote": null,
     "url": "/recordings/398"}
  ],
  "mode_used": "agent",
  "steps": 4,
  "usage": null
}

Every citation names a recording you can read. The question and the matching transcript passages go to the instance's chat model.

Events¶

Get Calendar Events¶

GET /api/v1/recordings/{id}/events

Scope: read

Returns calendar events extracted from the recording. The events in Get Recording Details are the same objects.

Response:

{
  "events": [
    {
      "id": 1,
      "recording_id": 412,
      "title": "Follow-up Meeting",
      "start_datetime": "2024-01-22T10:00:00",
      "end_datetime": "2024-01-22T11:00:00",
      "floating": true,
      "description": "Discuss project progress",
      "location": "Conference Room A",
      "attendees": [
        {"name": "Dana Lee", "email": null},
        {"name": "Priya Shah", "email": "priya@example.org"}
      ],
      "reminder_minutes": 15,
      "created_at": "2024-01-15T10:05:00"
    }
  ]
}

• floating: true: start_datetime and end_datetime are wall-clock times as said in the recording, without a time zone. Show them as they are, in the user's own zone.
• attendees are objects: a name, an address, or both. A name the transcript gave without an address has email: null.
• Before v0.10.11-alpha, attendees in the recording details were plain strings.

Download Events as ICS¶

GET /api/v1/recordings/{id}/events/ics

Scope: read

Returns an ICS file containing all events from the recording. Times are floating (no zone). Attendees with an address are ATTENDEE entries; names without an address are listed at the end of the description. reminder_minutes becomes an alarm.

Audio¶

Download Audio¶

GET /api/v1/recordings/{id}/audio

Scope: read

Query Parameters:

Batch Operations¶

Batch Update Recordings¶

PATCH /api/v1/recordings/batch

Scope: write

Request Body:

{
  "recording_ids": [1, 2, 3],
  "updates": {
    "is_inbox": false,
    "is_highlighted": true,
    "add_tag_ids": [5],
    "remove_tag_ids": [2],
    "folder_id": 5
  }
}

Supported updates fields: is_inbox, is_highlighted, add_tag_ids, remove_tag_ids, and folder_id (move all selected recordings into that folder, or null to remove them from their folders; you must have access to the target folder, and folders must be enabled). A 403 is returned if you lack access to the target folder, and 404 if it does not exist.

Response:

{
  "success": true,
  "updated": 3,
  "failed": 0,
  "results": [
    {"id": 1, "success": true},
    {"id": 2, "success": true},
    {"id": 3, "success": true}
  ]
}

Batch Delete Recordings¶

DELETE /api/v1/recordings/batch

Scope: delete

Request Body:

{
  "recording_ids": [1, 2, 3]
}

Batch Queue Transcriptions¶

POST /api/v1/recordings/batch/transcribe

Scope: process

Request Body:

{
  "recording_ids": [1, 2, 3]
}

Folders¶

Folders organize recordings into a one-to-many structure (a recording belongs to at most one folder).

Folders can be personal or group-scoped. Personal folders are editable only by their owner. Group folders are visible to all members of the group but editable only by group admins. Each folder's to_dict() includes a can_edit flag indicating whether the calling user may modify it.

List Folders¶

GET /api/v1/folders

Scope: read

Returns personal folders plus any group folders you have access to.

Response:

[
  {
    "id": 5,
    "name": "Client Calls",
    "color": "#10B981",
    "group_id": null,
    "is_group_folder": false,
    "group_name": null,
    "custom_prompt": "Focus on action items...",
    "default_language": "en",
    "default_min_speakers": 2,
    "default_max_speakers": 5,
    "default_hotwords": null,
    "default_initial_prompt": null,
    "default_transcription_model": null,
    "protect_from_deletion": false,
    "retention_days": null,
    "auto_share_on_apply": true,
    "share_with_group_lead": true,
    "naming_template_id": null,
    "naming_template_name": null,
    "export_template_id": null,
    "export_template_name": null,
    "created_at": "2024-01-10T08:00:00Z",
    "recording_count": 12,
    "can_edit": true,
    "user_role": null
  }
]

Get Folder¶

GET /api/v1/folders/{id}

Scope: read

Returns a single folder. You must own a personal folder, or be a member of the group for a group folder. The response is the folder object above (with can_edit).

Create Folder¶

POST /api/v1/folders

Scope: write

Request Body:

{
  "name": "Client Calls",
  "color": "#10B981",
  "group_id": null,
  "custom_prompt": "Focus on action items...",
  "default_language": "en",
  "default_min_speakers": 2,
  "default_max_speakers": 5,
  "default_hotwords": "Acme, Speakr",
  "default_initial_prompt": "Sales call.",
  "default_transcription_model": "gpt-4o-transcribe-diarize",
  "retention_days": null
}

Only name is required. Set group_id to create a group folder (you must be an admin of that group). Use retention_days: -1 to mark the folder as protected from auto-deletion (only effective when auto-deletion is enabled at the server). Returns the created folder with 201.

Update Folder¶

PATCH /api/v1/folders/{id}
PUT   /api/v1/folders/{id}

**Scope:** `write`

Accepts the same fields as create; all are optional. Only the folder owner (personal) or a group admin (group folder) may update. Returns the updated folder.

Delete Folder¶

DELETE /api/v1/folders/{id}

Scope: delete

Recordings in the deleted folder are unassigned (their folder_id becomes null); they are not deleted. Only the folder owner (personal) or a group admin (group folder) may delete.

Response:

{"success": true}

Transcription Connector¶

Discover Active Connector¶

GET /api/v1/transcription

Scope: read

Returns the active transcription connector, the optional fields it accepts, the admin-curated list of selectable models, and the configured default model. Use this to drive client UIs and to know which values are valid for the transcription_model override on /recordings/{id}/transcribe and /recordings/upload.

Response:

{
  "connector": "openai_transcribe",
  "capabilities": {
    "diarization": true,
    "speaker_count_control": false,
    "hotwords": true,
    "initial_prompt": true,
    "timestamps": true,
    "language_detection": true,
    "chunking": false
  },
  "models": [
    {"value": "gpt-4o-transcribe-diarize", "label": "GPT-4o Diarize"}
  ],
  "default_model": "gpt-4o-transcribe-diarize"
}

connector may be null when the legacy transcription architecture is in use. The capabilities flags indicate which optional request fields (hotwords, initial_prompt, speaker-count controls) the active connector honors; connectors that do not support a field drop it silently.

Webhooks¶

Webhooks deliver event notifications to an external URL when things happen to your recordings. Each webhook is owned by the user who creates it. The number of webhooks per user is capped (default 10, configurable by the administrator via WEBHOOK_MAX_PER_USER).

For administrator-level configuration and receiver setup, see the Webhooks admin guide.

Event Types¶

These are the event types a webhook can subscribe to:

List Webhooks¶

GET /api/v1/webhooks

Scope: webhooks

Response:

{
  "webhooks": [
    {
      "id": 1,
      "user_id": 42,
      "name": "n8n pipeline",
      "url": "https://hooks.example.com/speakr",
      "allow_http": false,
      "events": ["recording.transcription.completed", "recording.summary.completed"],
      "enabled": true,
      "auto_paused": false,
      "consecutive_failures": 0,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "last_delivery_at": "2024-01-16T09:30:00Z"
    }
  ],
  "event_types": [
    "recording.created",
    "recording.transcription.started",
    "recording.transcription.completed",
    "recording.transcription.failed",
    "recording.summary.completed",
    "recording.summary.failed",
    "recording.events.extracted",
    "recording.updated",
    "recording.deleted",
    "webhook.test"
  ],
  "max_per_user": 10
}

The webhook's HMAC secret is never returned by this endpoint. It is shown only once, in the create and rotate-secret responses.

Create Webhook¶

POST /api/v1/webhooks

Scope: webhooks

Request Body:

{
  "name": "n8n pipeline",
  "url": "https://hooks.example.com/speakr",
  "events": ["recording.transcription.completed"],
  "allow_http": false,
  "enabled": true
}

name, url, and a non-empty events array are required; every event must be a known event type. allow_http (default false) must be true for http:// URLs. The URL is validated against an SSRF guard. Exceeding the per-user cap returns 409.

Response (201): the webhook object, including the secret field once:

{
  "id": 1,
  "user_id": 42,
  "name": "n8n pipeline",
  "url": "https://hooks.example.com/speakr",
  "allow_http": false,
  "events": ["recording.transcription.completed"],
  "enabled": true,
  "auto_paused": false,
  "consecutive_failures": 0,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z",
  "last_delivery_at": null,
  "secret": "xK9...copy-me-now..."
}

Get Webhook¶

GET /api/v1/webhooks/{id}

Scope: webhooks

Returns the webhook object (without the secret).

Update Webhook¶

PATCH /api/v1/webhooks/{id}

Scope: webhooks

Request Body (all fields optional):

{
  "name": "Updated name",
  "url": "https://hooks.example.com/v2",
  "events": ["recording.transcription.completed", "recording.deleted"],
  "allow_http": false,
  "enabled": true
}

When provided, events must be a non-empty array of known event types. Setting enabled: true also clears the auto_paused flag. Returns the updated webhook.

Delete Webhook¶

DELETE /api/v1/webhooks/{id}

Scope: webhooks

Returns 204 No Content.

Rotate Secret¶

POST /api/v1/webhooks/{id}/rotate-secret

Scope: webhooks

Generates a fresh HMAC secret and returns the webhook object with the new secret included once. Existing deliveries already signed with the old secret are not re-signed.

Test Webhook¶

POST /api/v1/webhooks/{id}/test

Scope: webhooks

Enqueues a synthetic webhook.test delivery against this single webhook so you can verify reachability before subscribing to production events. The webhook must be enabled (otherwise 409).

Response (202): the created delivery object (see below).

List Deliveries¶

GET /api/v1/webhooks/{id}/deliveries

Scope: webhooks

Query Parameters:

Response:

{
  "deliveries": [
    {
      "id": 1001,
      "webhook_id": 1,
      "event_id": "550e8400-e29b-41d4-a716-446655440000",
      "event_type": "recording.transcription.completed",
      "attempt_count": 1,
      "status": "success",
      "response_status": 200,
      "response_body_preview": "{\"ok\":true}",
      "error_message": null,
      "next_retry_at": null,
      "created_at": "2024-01-16T09:30:00Z",
      "delivered_at": "2024-01-16T09:30:01Z"
    }
  ],
  "limit": 50
}

Delivery status is one of pending, success, failed (retryable), or permanent_failure (retries exhausted or non-retryable).

Get Delivery¶

GET /api/v1/webhooks/{id}/deliveries/{delivery_id}

Scope: webhooks

Returns a single delivery. This response additionally includes the full serialized payload (the exact JSON body that was/will be POSTed) for debugging.

Replay Delivery¶

POST /api/v1/webhooks/{id}/deliveries/{delivery_id}/replay

Scope: webhooks

Re-enqueues the delivery as a brand-new attempt with the same payload (with a fresh event_id and timestamp, plus a replayed_from reference to the original). Returns the new delivery object with 202.

Error Responses¶

All endpoints return consistent error responses:

{
  "error": "Error message description",
  "code": "insufficient_scope"
}

error is written in the interface language of the account that owns the token (Account > Interface Language), and in English when none is set. code is a machine-readable value that is the same in every language, for example insufficient_scope, invalid_parameter or not_found. A client is built on code and the HTTP status, not on the text of error. Errors that pass on the text of an unexpected exception carry no code.

Common HTTP Status Codes:

Rate Limits¶

Requests made with an API token are held by two limits for each kind of request. Both are counted separately for each endpoint:

• Token limit. Each token has its own budget, so two integrations with their own tokens do not share it.
• Account limit. On each endpoint, all tokens of one account draw on one budget, so a further token adds no throughput there.

An account limit that is not set is twice the token limit of the same kind, so a client with a single token is held by its token limit. Because both limits are per endpoint, a client that polls several endpoints, such as a mail client during a sync, is never refused by the account limit while each endpoint stays within its token limit. The limits apply to full-access and scoped tokens alike. A request that the token limit refuses does not count against the account limit.

A request over a limit gets 429 with a Retry-After header in seconds. The body names the limit that ran out:

{
  "error": "Rate limit reached for your account: 240 per minute (read requests on this endpoint), shared by all your API tokens.",
  "code": "account_rate_limit_exceeded",
  "limit": "240 per 1 minute"
}

code is token_rate_limit_exceeded for the token limit and account_rate_limit_exceeded for the account limit. Responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; while no limit is exceeded, these headers describe the token limit only. Base a client on the 429 body, not on the header values.

Requests from the web interface keep the per-address limits of the application (1000 per hour and 5000 per day). The ASR Voice Recorder upload carries its token in the form body, so neither limit applies to it; that endpoint keeps its own per-address limit.

Several worker processes. By default the counters are kept in the memory of each worker process. The standard image starts three gunicorn workers, so each limit, the login and registration limits included, is in effect up to about three times its configured value. With RATELIMIT_STORAGE_URI set to a Redis or Valkey server, the limits are exact. The image includes the Redis client. The server is run as a separate container, for example in the same Docker Compose file as Speakr:

  redis:
    image: redis:7.4-alpine
    restart: unless-stopped

with RATELIMIT_STORAGE_URI=redis://redis:6379/0 in .env. The counters need no persistence, so no volume is required. While the server is unreachable, counting falls back to the memory of each process and requests are served as before. A Memcached URI (memcached://) is also accepted, in an image with the pymemcache package added; Speakr does not start with a backend URI whose client is missing.

Integration Examples¶

Python SDK Pattern¶

import requests

class SpeakrAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url.rstrip('/')
        self.session = requests.Session()
        self.session.headers['Authorization'] = f'Bearer {token}'

    def get_stats(self):
        return self.session.get(f'{self.base_url}/api/v1/stats').json()

    def list_recordings(self, status='all', page=1):
        return self.session.get(
            f'{self.base_url}/api/v1/recordings',
            params={'status': status, 'page': page}
        ).json()

    def get_transcript(self, recording_id, format='text'):
        return self.session.get(
            f'{self.base_url}/api/v1/recordings/{recording_id}/transcript',
            params={'format': format}
        ).json()

# Usage
api = SpeakrAPI('https://speakr.example.com', 'YOUR_TOKEN')
stats = api.get_stats()
print(f"Total recordings: {stats['recordings']['total']}")