Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
"""
API v1 - RESTful API for external integrations.
This blueprint provides a comprehensive REST API for:
- Dashboard widgets (gethomepage.dev, etc.)
- Automation tools (n8n, Zapier, etc.)
- Third-party integrations
All endpoints require token authentication via:
- Authorization: Bearer <token>
- X-API-Token: <token>
- API-Token: <token>
- ?token=<token> query parameter
"""
import os
import re
import json
import math
from datetime import datetime, date, timedelta, timezone
from functools import wraps
from src.utils.dates import to_utc_naive
from typing import Optional
from flask import Blueprint, jsonify, request, current_app, send_file, redirect
from flask_login import login_required, current_user
from src.utils.token_auth import require_scope, token_rate_key
from sqlalchemy import func, extract, or_, and_
from werkzeug.exceptions import RequestEntityTooLarge
from werkzeug.utils import secure_filename
from src.database import db
from src.services.recording_state import get_user_archived, set_user_archived, parse_archived_flag
from src.models import Recording, User, Tag, RecordingTag, Speaker, Event
from src.models.processing_job import ProcessingJob
from src.models.token_usage import TokenUsage
from src.models.transcription_usage import TranscriptionUsage
from src.services.token_tracking import TokenTracker
from src.services.transcription_tracking import transcription_tracker
from src.file_exporter import format_transcription_with_template
from src.api.recordings import (
ingest_uploaded_recording,
upload_file as _upload_file_ui,
)
from src.services.storage import get_storage_service
from src.utils.mime import served_media_mime, sandbox_media_response
from src.utils.token_auth import load_user_from_token_value
from src.utils.localization import api_error, translate
# Create blueprint with /api/v1 prefix
api_v1_bp = Blueprint('api_v1', __name__, url_prefix='/api/v1')
# Global helpers (will be injected from app)
has_recording_access = None
get_user_recording_status = None
set_user_recording_status = None
enrich_recording_dict_with_user_status = None
bcrypt = None
csrf = None
limiter = None
chunking_service = None
# Token tracker instance
token_tracker = TokenTracker()
def init_api_v1_helpers(**kwargs):
"""Initialize helper functions and extensions from app."""
global has_recording_access, get_user_recording_status, set_user_recording_status
global enrich_recording_dict_with_user_status, bcrypt, csrf, limiter, chunking_service
has_recording_access = kwargs.get('has_recording_access')
get_user_recording_status = kwargs.get('get_user_recording_status')
set_user_recording_status = kwargs.get('set_user_recording_status')
enrich_recording_dict_with_user_status = kwargs.get('enrich_recording_dict_with_user_status')
bcrypt = kwargs.get('bcrypt')
csrf = kwargs.get('csrf')
limiter = kwargs.get('limiter')
chunking_service = kwargs.get('chunking_service')
def rate_limit(limit_string, **limit_options):
"""Apply an endpoint limit after the app injects Flask-Limiter."""
def decorator(f):
state = {'limited': None}
@wraps(f)
def wrapper(*args, **kwargs):
if limiter is not None and getattr(limiter, 'enabled', True):
if state['limited'] is None:
state['limited'] = limiter.limit(limit_string, **limit_options)(f)
return state['limited'](*args, **kwargs)
return f(*args, **kwargs)
wrapper._rate_limit = limit_string
wrapper._rate_limit_options = limit_options
# functools.wraps copies these attributes onto any decorator above;
# this one points at this wrapper only, so require_scope can tell it
# apart from a decorator that merely inherited them.
wrapper._rate_limit_wrapper = wrapper
return wrapper
return decorator
def format_bytes(bytes_value: int) -> str:
"""Format bytes to human-readable string."""
if bytes_value is None:
bytes_value = 0
for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
if bytes_value < 1024:
return f"{bytes_value:.1f} {unit}"
bytes_value /= 1024
return f"{bytes_value:.1f} PB"
# =============================================================================
# OpenAPI Documentation
# =============================================================================
OPENAPI_SPEC = {
"openapi": "3.0.3",
"info": {
"title": "Speakr API",
"description": "REST API for Speakr - Audio transcription and note-taking application.\n\n## Authentication\nMost endpoints require token authentication via one of:\n- `Authorization: Bearer <token>`\n- `X-API-Token: <token>`\n- `API-Token: <token>`\n- `?token=<token>` query parameter\n\nThe ASR Voice Recorder integration is the one exception: its required multipart `secret` field contains the personal Speakr API token because that client cannot set custom authorization headers. Generate tokens in Settings > API Tokens.",
"version": "1.0.0"
},
"servers": [{"url": "/api/v1", "description": "API v1"}],
"components": {
"securitySchemes": {
"bearerAuth": {"type": "http", "scheme": "bearer",
"description": "A personal API token. Tokens may carry scopes: read, write, upload, "
"process, share, delete, webhooks, account. A token with no scopes "
"(reported as [\"full\"]) has every scope. Each operation lists the "
"scopes it needs in x-required-scopes; a scoped token without them "
"gets 403 insufficient_scope. Scoped tokens work only in a header."},
"apiKeyHeader": {"type": "apiKey", "in": "header", "name": "X-API-Token"},
"apiKeyQuery": {"type": "apiKey", "in": "query", "name": "token"}
},
"schemas": {
"Recording": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"title": {"type": "string"},
"status": {"type": "string", "enum": ["PENDING", "PROCESSING", "SUMMARIZING", "COMPLETED", "FAILED"]},
"created_at": {"type": "string", "format": "date-time"},
"meeting_date": {"type": "string", "format": "date-time"},
"file_size": {"type": "integer"},
"audio_duration": {"type": "number", "description": "Audio duration in seconds"},
"transcription_duration_seconds": {"type": "integer", "description": "Wall-clock seconds spent transcribing"},
"summarization_duration_seconds": {"type": "integer", "description": "Wall-clock seconds spent summarizing"},
"participants": {"type": "string"},
"is_inbox": {"type": "boolean"},
"is_highlighted": {"type": "boolean"},
"is_archived": {"type": "boolean", "description": "Hidden from the main list in the web app; nothing is deleted"},
"deletion_exempt": {"type": "boolean", "description": "If true, recording is exempt from auto-deletion"},
"prompt_variables": {"type": "object", "description": "Per-recording {{name}} substitutions used when summarising"},
"folder_id": {"type": "integer", "nullable": True},
"folder": {"type": "object", "nullable": True, "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}},
"events": {"type": "array", "description": "Calendar events extracted from the recording (detail endpoint only)", "items": {"type": "object"}},
"tags": {"type": "array", "items": {"$ref": "#/components/schemas/Tag"}},
"keep_audio_only": {"type": "boolean", "description": "True if the upload was processed in audio-only mode (video stream discarded). Set at upload time; immutable via PATCH."},
"updated_at": {"type": "string", "format": "date-time", "description": "Last change a client can see; starts at created_at"},
"is_shared": {"type": "boolean"},
"owner": {"type": "object", "nullable": True},
"share": {"type": "object", "nullable": True},
"external_refs": {"type": "array", "items": {"type": "object"}}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"color": {"type": "string"},
"custom_prompt": {"type": "string"},
"title_prompt": {"type": "string"},
"default_language": {"type": "string"},
"default_min_speakers": {"type": "integer"},
"default_max_speakers": {"type": "integer"},
"default_hotwords": {"type": "string"},
"default_initial_prompt": {"type": "string"},
"default_transcription_model": {"type": "string"}
}
},
"Folder": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"color": {"type": "string"},
"group_id": {"type": "integer", "nullable": True},
"is_group_folder": {"type": "boolean"},
"custom_prompt": {"type": "string"},
"title_prompt": {"type": "string"},
"default_language": {"type": "string"},
"default_min_speakers": {"type": "integer"},
"default_max_speakers": {"type": "integer"},
"default_hotwords": {"type": "string"},
"default_initial_prompt": {"type": "string"},
"default_transcription_model": {"type": "string"},
"protect_from_deletion": {"type": "boolean"},
"retention_days": {"type": "integer", "nullable": True},
"recording_count": {"type": "integer"}
}
},
"Speaker": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"use_count": {"type": "integer"},
"has_voice_profile": {"type": "boolean"}
}
},
"Error": {
"type": "object",
"properties": {"error": {"type": "string"},
"code": {"type": "string", "description": "Machine-readable error code, e.g. insufficient_scope"}}
},
"TokenInfo": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"scopes": {"type": "array", "items": {"type": "string"}},
"created_at": {"type": "string", "format": "date-time"},
"expires_at": {"type": "string", "format": "date-time", "nullable": True},
"last_used_at": {"type": "string", "format": "date-time", "nullable": True},
"via": {"type": "string", "enum": ["header", "query"]}
}
},
"Capabilities": {
"type": "object",
"properties": {
"speakr_version": {"type": "string"},
"api_version": {"type": "string"},
"features": {"type": "object", "additionalProperties": True,
"description": "Feature flags; a missing key means false"},
"models_local": {"type": "boolean"}
}
}
}
},
"security": [{"bearerAuth": []}, {"apiKeyHeader": []}, {"apiKeyQuery": []}],
"paths": {
"/tokens/current": {
"get": {
"tags": ["Tokens"],
"summary": "The API token used for this request",
"description": "Any valid token, no scope needed. A session request gets 404.",
"responses": {"200": {"description": "Token details",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/TokenInfo"}}}},
"404": {"description": "No API token in this request"}}
}
},
"/capabilities": {
"get": {
"tags": ["Tokens"],
"summary": "Features this instance supports",
"description": "Any valid token or session. Clients read features here, never from the version string.",
"responses": {"200": {"description": "Capabilities",
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Capabilities"}}}}}
}
},
"/search": {
"get": {
"tags": ["Recordings"],
"summary": "Search titles, participants, notes, summaries and transcripts",
"description": "Keyword search over every recording you own, or semantic search through the Inquire index (mode=semantic). Transcript hits carry segment_index, start_time, end_time and speaker.",
"parameters": [
{"name": "q", "in": "query", "required": True, "schema": {"type": "string"}},
{"name": "mode", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "fields", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "scope", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "recording_ids", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "tag_id", "in": "query", "required": False, "schema": {"type": "integer"}},
{"name": "folder_id", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "speaker", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "date_from", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "date_to", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "date_field", "in": "query", "required": False, "schema": {"type": "string"}},
{"name": "limit", "in": "query", "required": False, "schema": {"type": "integer"}},
{"name": "page", "in": "query", "required": False, "schema": {"type": "integer"}}
],
"responses": {"200": {"description": "Hits"}, "400": {"description": "invalid_parameter"},
"409": {"description": "semantic_unavailable"}}
}
},
"/recordings/changes": {
"get": {
"tags": ["Recordings"],
"summary": "Changes to your recordings since a cursor",
"description": "Each create, edit and delete once, in latest state. Store next_cursor after every answer. 410 cursor_expired: start again without a cursor.",
"parameters": [
{"name": "cursor", "in": "query", "schema": {"type": "string"}},
{"name": "limit", "in": "query", "schema": {"type": "integer", "default": 100, "minimum": 1, "maximum": 500}},
{"name": "scope", "in": "query", "schema": {"type": "string", "enum": ["own", "shared", "all"], "default": "own"}}
],
"responses": {
"200": {"description": "A page of changes", "content": {"application/json": {"schema": {
"type": "object",
"properties": {
"changes": {"type": "array", "items": {"type": "object", "properties": {
"type": {"type": "string", "enum": ["upsert", "delete"]},
"recording": {"$ref": "#/components/schemas/Recording"},
"id": {"type": "integer"},
"deleted_at": {"type": "string", "format": "date-time"},
"reason": {"type": "string", "enum": ["deleted", "retention", "access_revoked"]}}}},
"next_cursor": {"type": "string"},
"has_more": {"type": "boolean"}}}}}},
"400": {"description": "invalid_parameter"},
"410": {"description": "cursor_expired"}
}
}
},
"/stats": {
"get": {
"tags": ["Stats"],
"summary": "Get system statistics",
"description": "Returns stats compatible with gethomepage.dev widgets",
"parameters": [{"name": "scope", "in": "query", "schema": {"type": "string", "enum": ["user", "all"], "default": "user"}, "description": "user=personal stats, all=global (admin only)"}],
"responses": {"200": {"description": "Stats object"}}
}
},
"/users/me": {
"get": {
"tags": ["Users"],
"summary": "Get current user profile",
"description": "Returns the authenticated user's profile (id, username, email, name, role flags, preferences), group memberships, and storage (used_bytes, quota_bytes, available_bytes; quota_bytes is null when there is no quota).",
"responses": {"200": {"description": "User profile object"}}
}
},
"/recordings": {
"get": {
"tags": ["Recordings"],
"summary": "List recordings",
"parameters": [
{"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}},
{"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 25, "maximum": 100}},
{"name": "status", "in": "query", "schema": {"type": "string", "enum": ["all", "pending", "processing", "completed", "failed"]}},
{"name": "sort_by", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date", "title", "file_size", "status", "updated_at"]}},
{"name": "updated_since", "in": "query", "schema": {"type": "string", "format": "date-time"}, "description": "Only recordings changed after this time"},
{"name": "date_field", "in": "query", "schema": {"type": "string", "enum": ["created_at", "meeting_date"], "default": "created_at"}, "description": "What date_from and date_to filter"},
{"name": "scope", "in": "query", "schema": {"type": "string", "enum": ["own", "shared", "all"], "default": "own"}},
{"name": "owner_id", "in": "query", "schema": {"type": "integer"}},
{"name": "sort_order", "in": "query", "schema": {"type": "string", "enum": ["asc", "desc"]}},
{"name": "tag_id", "in": "query", "schema": {"type": "integer"}},
{"name": "archived", "in": "query", "schema": {"type": "boolean"}, "description": "true: only archived recordings; false: only unarchived. Omitted: both, as before."},
{"name": "folder_id", "in": "query", "schema": {"type": "string"}, "description": "Filter by folder. Pass an integer folder id to list recordings in that folder, or the literal 'none' to list recordings not in any folder. Omit for no filter."},
{"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Search query"}
],
"responses": {"200": {"description": "Paginated list of recordings"}}
}
},
"/recordings/{id}": {
"get": {
"tags": ["Recordings"],
"summary": "Get recording details",
"parameters": [
{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}},
{"name": "format", "in": "query", "schema": {"type": "string", "enum": ["full", "minimal"]}, "description": "minimal excludes large text fields"},
{"name": "include", "in": "query", "schema": {"type": "string"}, "description": "Comma-separated: transcription,summary,notes"}
],
"responses": {"200": {"description": "Recording details"}, "404": {"description": "Not found"}}
},
"patch": {
"tags": ["Recordings"],
"summary": "Update recording",
"parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
"requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"title": {"type": "string"}, "participants": {"type": "string"}, "notes": {"type": "string"}, "summary": {"type": "string"}, "meeting_date": {"type": "string"}, "is_inbox": {"type": "boolean"}, "is_highlighted": {"type": "boolean"}, "is_archived": {"type": "boolean"}, "folder_id": {"type": "integer", "nullable": True, "description": "Move recording to this folder, or null to remove from any folder. Caller must have access to the target folder."}}}}}},
"responses": {"200": {"description": "Updated recording"}, "403": {"description": "No access to target folder"}, "404": {"description": "Recording or folder not found"}}
},
"delete": {
"tags": ["Recordings"],
"summary": "Delete recording",
"parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
"responses": {"200": {"description": "Deleted"}, "403": {"description": "Permission denied"}}
}
},
"/recordings/{id}/transcript": {
"get": {
"tags": ["Recordings"],
"summary": "Get transcript",
"parameters": [
{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}},
{"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "text", "srt", "vtt"], "default": "json"}}
],
"responses": {"200": {"description": "Transcript in requested format"}}
}
},
"/recordings/{id}/summary": {
"get": {"tags": ["Recordings"], "summary": "Get summary", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Summary markdown"}}},
"put": {"tags": ["Recordings"], "summary": "Replace summary", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["summary"], "properties": {"summary": {"type": "string"}}}}}}, "responses": {"200": {"description": "Updated"}}}
},
"/recordings/{id}/notes": {
"get": {"tags": ["Recordings"], "summary": "Get notes", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Notes markdown"}}},
"put": {"tags": ["Recordings"], "summary": "Replace notes", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["notes"], "properties": {"notes": {"type": "string"}}}}}}, "responses": {"200": {"description": "Updated"}}}
},
"/recordings/{id}/delete-audio": {
"post": {"tags": ["Recordings"], "summary": "Delete audio, keep transcript", "description": "Deletes the media file and keeps the transcript, summary and notes. Same permission as deleting the recording. 409 if the audio is already removed or the recording is still processing.", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Audio removed"}, "403": {"description": "Permission denied"}, "404": {"description": "Recording not found"}, "409": {"description": "Already removed or still processing"}}}
},
"/recordings/{id}/status": {
"get": {"tags": ["Recordings"], "summary": "Get processing status", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Status with queue position"}}}
},
"/recordings/{id}/transcribe": {
"post": {"tags": ["Processing"], "summary": "Queue transcription", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"language": {"type": "string"}, "min_speakers": {"type": "integer"}, "max_speakers": {"type": "integer"}, "hotwords": {"type": "string", "description": "Connectors that accept hotword biasing route this to their native parameter (WhisperX hotwords, Mistral context_bias, OpenAI prompt, etc.). Connectors that ignore it drop it silently."}, "initial_prompt": {"type": "string", "description": "Free-text context hint. Same per-connector behaviour as hotwords."}, "transcription_model": {"type": "string", "description": "Per-request model override. Validated against the admin-curated visible-models list. Falls back to the configured default if absent or invalid."}}}}}}, "responses": {"200": {"description": "Job queued"}}}
},
"/recordings/{id}/summarize": {
"post": {"tags": ["Processing"], "summary": "Queue summarization", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"custom_prompt": {"type": "string"}}}}}}, "responses": {"200": {"description": "Job queued"}}}
},
"/recordings/{id}/chat": {
"post": {"tags": ["Chat"], "summary": "Chat about recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["message"], "properties": {"message": {"type": "string"}, "conversation_history": {"type": "array"}}}}}}, "responses": {"200": {"description": "Chat response"}}}
},
"/recordings/{id}/events": {
"get": {"tags": ["Events"], "summary": "Get calendar events", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "List of events"}}}
},
"/recordings/{id}/events/ics": {
"get": {"tags": ["Events"], "summary": "Download events as ICS", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "ICS file", "content": {"text/calendar": {}}}}}
},
"/recordings/{id}/audio": {
"get": {"tags": ["Audio"], "summary": "Download audio", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}, {"name": "download", "in": "query", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Audio file"}}}
},
"/recordings/{id}/tags": {
"post": {"tags": ["Tags"], "summary": "Add tags to recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"tag_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Tags added"}}}
},
"/recordings/{id}/tags/{tag_id}": {
"delete": {"tags": ["Tags"], "summary": "Remove tag from recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}, {"name": "tag_id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Tag removed"}}}
},
"/recordings/{id}/speakers": {
"get": {"tags": ["Speakers"], "summary": "Get speakers in recording", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Speakers with suggestions"}}}
},
"/recordings/{id}/speakers/assign": {
"put": {
"tags": ["Speakers"],
"summary": "Assign speaker names to transcription",
"parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
"requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["speaker_map"], "properties": {"speaker_map": {"type": "object", "description": "Map of speaker labels to names. Values can be: string (name) or object {name, isMe}."}, "regenerate_summary": {"type": "boolean", "default": False}}}}}},
"responses": {"200": {"description": "Speakers assigned"}, "404": {"description": "Recording not found"}, "403": {"description": "Permission denied"}}
}
},
"/recordings/{id}/speakers/identify": {
"post": {
"tags": ["Speakers"],
"summary": "Auto-identify speakers via LLM",
"description": "Analyzes transcript context to suggest speaker names. Returns suggestions only - does not modify the recording.",
"parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
"responses": {"200": {"description": "Speaker identification suggestions"}, "400": {"description": "Transcription not available or unsupported format"}}
}
},
"/recordings/batch": {
"patch": {"tags": ["Batch"], "summary": "Batch update recordings", "description": "Apply the same set of updates to multiple recordings in one call. Supported fields inside `updates`: `is_inbox`, `is_highlighted`, `is_archived`, `add_tag_ids` (array of tag ids to add), `remove_tag_ids` (array of tag ids to remove), `folder_id` (move all to this folder, or null to remove from any folder).", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids", "updates"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}, "updates": {"type": "object", "properties": {"is_inbox": {"type": "boolean"}, "is_highlighted": {"type": "boolean"}, "is_archived": {"type": "boolean"}, "add_tag_ids": {"type": "array", "items": {"type": "integer"}}, "remove_tag_ids": {"type": "array", "items": {"type": "integer"}}, "folder_id": {"type": "integer", "nullable": True, "description": "Target folder id, or null to remove all selected recordings from their folders. Caller must have access."}}}}}}}}, "responses": {"200": {"description": "Batch results"}, "403": {"description": "No access to target folder"}, "404": {"description": "Target folder not found"}}},
"delete": {"tags": ["Batch"], "summary": "Batch delete recordings", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Batch results"}}}
},
"/recordings/batch/transcribe": {
"post": {"tags": ["Batch"], "summary": "Batch queue transcriptions", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["recording_ids"], "properties": {"recording_ids": {"type": "array", "items": {"type": "integer"}}}}}}}, "responses": {"200": {"description": "Batch results"}}}
},
"/recordings/upload": {
"post": {
"tags": ["Recordings"],
"summary": "Upload a recording (multipart form-data) and queue transcription",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": ["file"],
"properties": {
"file": {"type": "string", "format": "binary"},
"notes": {"type": "string"},
"title": {"type": "string"},
"meeting_date": {"type": "string", "format": "date-time"},
"file_last_modified": {"type": "string"},
"language": {"type": "string"},
"min_speakers": {"type": "integer"},
"max_speakers": {"type": "integer"},
"hotwords": {"type": "string"},
"initial_prompt": {"type": "string"},
"transcription_model": {"type": "string"},
"prompt_variables": {"type": "string", "description": "JSON object of {variable_name: value} substituted into {{name}} placeholders in the summary prompt"},
"folder_id": {"type": "integer"},
"tag_id": {"type": "integer"},
"tag_ids[0]": {"type": "integer"},
"tag_ids[1]": {"type": "integer"},
"keep_audio_only": {"type": "boolean", "description": "If true, the server discards the video stream and stores only the extracted audio. Allows uploads up to max_audio_only_video_size_mb (vs max_file_size_mb) for video files, as long as the extracted audio still fits the regular limit."}
}
}
}
}
},
"responses": {"202": {"description": "Upload accepted and queued"}, "400": {"description": "Invalid parameters, or a file that cannot be ingested (code empty_file or audio_decode_failed)"}, "507": {"description": "The upload would exceed the user's storage quota (code storage_quota_exceeded, with used_bytes, quota_bytes and file_bytes)"}}
}
},
"/integrations/asr-voice-recorder/upload": {
"post": {
"tags": ["Integrations"],
"summary": "Receive a completed ASR Voice Recorder recording",
"description": (
"Accepts ASR Voice Recorder's multipart webhook format and queues the "
"recording through Speakr's normal transcription pipeline. It also accepts "
"ASR's authenticated, fileless connection test without creating a recording. "
"The required `secret` field must contain a personal Speakr API token. Session "
"cookies and the API's normal authentication headers do not authenticate this endpoint."
),
"security": [],
"requestBody": {
"required": True,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": ["secret"],
"properties": {
"file": {"type": "string", "format": "binary", "description": "Required for a completed recording upload; omitted by ASR's connection test"},
"file_name": {"type": "string", "description": "Optional original filename override"},
"secret": {"type": "string", "format": "password", "writeOnly": True, "description": "A personal Speakr API token"},
"date": {"type": "integer", "format": "int64", "description": "Recording time as Unix epoch seconds or milliseconds"},
"duration": {"type": "number", "description": "Accepted for ASR compatibility but ignored; Speakr measures the media duration"},
"note": {"type": "string", "description": "Stored as the recording notes"},
},
}
}
},
},
"responses": {
"200": {"description": "Connection test passed, recording accepted, or an idempotent retry matched an existing recording"},
"400": {"description": "Upload metadata was provided without a file, the multipart request is invalid, or the file cannot be ingested (code empty_file or audio_decode_failed)"},
"401": {"description": "Missing, invalid, expired, or revoked API token"},
"413": {"description": "Upload exceeds the configured size limit"},
"429": {"description": "Too many upload attempts"},
"500": {"description": "Upload or queueing failed"},
},
}
},
"/tags": {
"get": {"tags": ["Tags"], "summary": "List tags", "responses": {"200": {"description": "List of tags"}}},
"post": {"tags": ["Tags"], "summary": "Create tag", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}, "title_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}}}}}}, "responses": {"201": {"description": "Tag created"}}}
},
"/tags/{id}": {
"put": {"tags": ["Tags"], "summary": "Update tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}, "title_prompt": {"type": "string"}}}}}}, "responses": {"200": {"description": "Tag updated"}}},
"delete": {"tags": ["Tags"], "summary": "Delete tag", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Tag deleted"}}}
},
"/folders": {
"get": {"tags": ["Folders"], "summary": "List folders", "responses": {"200": {"description": "Array of folders the user can access", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/Folder"}}}}}}},
"post": {"tags": ["Folders"], "summary": "Create folder", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "group_id": {"type": "integer", "nullable": True}, "custom_prompt": {"type": "string"}, "title_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}, "default_hotwords": {"type": "string"}, "default_initial_prompt": {"type": "string"}, "default_transcription_model": {"type": "string"}, "retention_days": {"type": "integer"}}}}}}, "responses": {"201": {"description": "Folder created"}}}
},
"/folders/{id}": {
"get": {"tags": ["Folders"], "summary": "Get folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Folder", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Folder"}}}}}},
"patch": {"tags": ["Folders"], "summary": "Update folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "color": {"type": "string"}, "custom_prompt": {"type": "string"}, "title_prompt": {"type": "string"}, "default_language": {"type": "string"}, "default_min_speakers": {"type": "integer"}, "default_max_speakers": {"type": "integer"}, "default_hotwords": {"type": "string"}, "default_initial_prompt": {"type": "string"}, "default_transcription_model": {"type": "string"}, "retention_days": {"type": "integer"}}}}}}, "responses": {"200": {"description": "Folder updated"}}},
"delete": {"tags": ["Folders"], "summary": "Delete folder", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Folder deleted"}}}
},
"/transcription": {
"get": {
"tags": ["Transcription"],
"summary": "Discover the active transcription connector and its accepted models",
"description": "Returns the active connector name, a map of capability flags, the admin-curated model list, 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.",
"responses": {
"200": {
"description": "Connector info",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"connector": {"type": "string", "nullable": True, "description": "Active connector name (e.g. asr_endpoint, openai_transcribe, mistral, vibevoice)"},
"capabilities": {
"type": "object",
"description": "Boolean flags indicating which optional fields the connector accepts",
"properties": {
"diarization": {"type": "boolean"},
"speaker_count_control": {"type": "boolean"},
"hotwords": {"type": "boolean"},
"initial_prompt": {"type": "boolean"},
"timestamps": {"type": "boolean"},
"language_detection": {"type": "boolean"},
"chunking": {"type": "boolean"}
}
},
"models": {
"type": "array",
"description": "Models the admin has marked visible to users (or TRANSCRIPTION_MODELS_AVAILABLE entries when no DB list is set)",
"items": {
"type": "object",
"properties": {
"value": {"type": "string"},
"label": {"type": "string"}
}
}
},
"default_model": {"type": "string", "nullable": True}
}
}
}
}
}
}
}
},
"/speakers": {
"get": {"tags": ["Speakers"], "summary": "List speakers", "responses": {"200": {"description": "List of speakers"}}},
"post": {"tags": ["Speakers"], "summary": "Create speaker", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}}}}}}, "responses": {"201": {"description": "Speaker created"}}}
},
"/speakers/{id}": {
"put": {"tags": ["Speakers"], "summary": "Update speaker", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}}}, "responses": {"200": {"description": "Speaker updated"}}},
"delete": {"tags": ["Speakers"], "summary": "Delete speaker", "parameters": [{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Speaker deleted"}}}
},
"/settings/auto-summarization": {
"put": {
"tags": ["Settings"],
"summary": "Toggle auto-summarization",
"description": "Enable or disable auto-summarization for the current user.",
"requestBody": {"content": {"application/json": {"schema": {"type": "object", "required": ["enabled"], "properties": {"enabled": {"type": "boolean"}}}}}},
"responses": {"200": {"description": "Setting updated"}}
}
}
},
"tags": [
{"name": "Stats", "description": "System statistics for dashboards"},
{"name": "Recordings", "description": "Recording CRUD operations"},
{"name": "Processing", "description": "Transcription and summarization"},
{"name": "Chat", "description": "Chat with recordings"},
{"name": "Events", "description": "Calendar events"},
{"name": "Audio", "description": "Audio file operations"},
{"name": "Tags", "description": "Tag management"},
{"name": "Folders", "description": "Folder management"},
{"name": "Transcription", "description": "Transcription connector and model discovery"},
{"name": "Speakers", "description": "Speaker management"},
{"name": "Batch", "description": "Batch operations"},
{"name": "Settings", "description": "User settings"},
{"name": "Tokens", "description": "Token introspection and instance capabilities"}
]
}
def _openapi_with_scopes():
"""OPENAPI_SPEC with x-required-scopes on every operation, read from the
routes' require_scope marks so the document cannot drift from the code.
Every operation also gets an operationId (#443), which tools that turn
an OpenAPI document into LLM tools (Open WebUI, for one) require. It is
the view function's name, with the method appended when one function
serves several methods, so it stays the same across releases unless the
function is renamed."""
import copy
import re
from flask import current_app
spec = copy.deepcopy(OPENAPI_SPEC)
norm = lambda path: re.sub(r'<[^>]+>|\{[^}]+\}', '{}', path)
by_route = {}
view_names = {}
for rule in current_app.url_map.iter_rules():
if not rule.rule.startswith('/api/v1/'):
continue
name = rule.endpoint.rsplit('.', 1)[-1]
methods = rule.methods - {'HEAD', 'OPTIONS'}
for method in methods:
view_names[(norm(rule.rule[len('/api/v1'):]), method.lower())] = (name, len(methods) > 1)
view = current_app.view_functions.get(rule.endpoint)
scopes = getattr(view, '_required_scopes', None)
if scopes is None:
continue
for method in methods:
by_route[(norm(rule.rule[len('/api/v1'):]), method.lower())] = sorted(scopes)
used_ids = set()
for path, operations in spec.get('paths', {}).items():
for method, operation in operations.items():
if not isinstance(operation, dict):
continue
scopes = by_route.get((norm(path), method))
if scopes is not None:
operation['x-required-scopes'] = scopes
if 'operationId' not in operation:
name, shared = view_names.get(
(norm(path), method),
(re.sub(r'\W+', '_', path).strip('_'), True))
op_id = f'{name}_{method}' if shared else name
while op_id in used_ids:
op_id += '_'
operation['operationId'] = op_id
used_ids.add(operation['operationId'])
return spec
@api_v1_bp.route('/openapi.json', methods=['GET'])
@require_scope('read')
def get_openapi_spec():
"""Return OpenAPI specification."""
return jsonify(_openapi_with_scopes())
@api_v1_bp.route('/docs', methods=['GET'])
@require_scope('read')
def get_docs():
"""Serve Swagger UI documentation.
Assets are served from Speakr's own vendored copy (static/vendor) rather than
a public CDN so the page works under the default Content-Security-Policy
(script-src/style-src 'self') without any per-route CSP relaxation.
"""
from flask import Response, url_for
css_url = url_for('static', filename='vendor/css/swagger-ui.css')
bundle_url = url_for('static', filename='vendor/js/swagger-ui-bundle.js')
html = f'''<!DOCTYPE html>
<html>
<head>
<title>Speakr API v1 Documentation</title>
<link rel="stylesheet" href="{css_url}" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="{bundle_url}"></script>
<script>
SwaggerUIBundle({{
url: "/api/v1/openapi.json",
dom_id: '#swagger-ui',
presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
layout: "BaseLayout",
persistAuthorization: true
}});
</script>
</body>
</html>'''
return Response(html, mimetype='text/html')
# =============================================================================
# Stats Endpoint (Homepage Widget Compatible)
# =============================================================================
@api_v1_bp.route('/stats', methods=['GET'])
@require_scope('read')
@login_required
def get_stats():
"""
Get system/user statistics for dashboard widgets.
Query params:
scope: 'user' (default) or 'all' (admin only)
Returns JSON compatible with gethomepage.dev custom API widget:
{
"recordings": {"total": N, "completed": N, "processing": N, "pending": N, "failed": N},
"storage": {"used_bytes": N, "used_human": "X.X GB"},
"queue": {"jobs_queued": N, "jobs_processing": N},
"tokens": {"used_this_month": N, "budget": N, "percentage": N},
"transcription": {"used_this_month_seconds": N, "used_this_month_minutes": N, "budget_seconds": N, "budget_minutes": N, "percentage": N, "estimated_cost": N},
"activity": {"recordings_today": N, "last_transcription": "ISO datetime"}
}
"""
scope = request.args.get('scope', 'user')
# Admin-only for global stats
if scope == 'all' and not current_user.is_admin:
return jsonify(api_error('global_stats_admin_only')), 403
# Build query filters based on scope
if scope == 'user':
recording_filter = Recording.user_id == current_user.id
job_filter = ProcessingJob.user_id == current_user.id
user_id_for_tokens = current_user.id
else:
recording_filter = True # No filter = all recordings
job_filter = True
user_id_for_tokens = None # Will aggregate all users
# Recording counts by status
total = Recording.query.filter(recording_filter).count()
completed = Recording.query.filter(recording_filter, Recording.status == 'COMPLETED').count()
processing = Recording.query.filter(
recording_filter,
Recording.status.in_(['PROCESSING', 'SUMMARIZING'])
).count()
pending = Recording.query.filter(recording_filter, Recording.status == 'PENDING').count()
failed = Recording.query.filter(recording_filter, Recording.status == 'FAILED').count()
# Storage calculation. Exclude recordings whose audio was removed by
# audio-only retention (audio_deleted_at set) — the file is gone but
# file_size is still recorded, so summing it overcounts actual storage.
storage_query = db.session.query(func.sum(Recording.file_size)).filter(
recording_filter, Recording.audio_deleted_at.is_(None))
storage_bytes = storage_query.scalar() or 0
# Queue status
jobs_queued = ProcessingJob.query.filter(
job_filter,
ProcessingJob.status == 'queued'
).count()
jobs_processing = ProcessingJob.query.filter(
job_filter,
ProcessingJob.status == 'processing'
).count()
# Token usage
tokens_data = {}
if user_id_for_tokens:
# Single user stats
monthly_usage = token_tracker.get_monthly_usage(user_id_for_tokens)
user = db.session.get(User, user_id_for_tokens)
budget = user.monthly_token_budget if user else None
tokens_data = {
'used_this_month': monthly_usage,
'budget': budget,
'percentage': round((monthly_usage / budget * 100), 1) if budget else None
}
else:
# Aggregate all users (admin scope)
current_year = date.today().year
current_month = date.today().month
total_usage = db.session.query(func.sum(TokenUsage.total_tokens)).filter(
extract('year', TokenUsage.date) == current_year,
extract('month', TokenUsage.date) == current_month
).scalar() or 0
tokens_data = {
'used_this_month': total_usage,
'budget': None,
'percentage': None
}
# Transcription usage
transcription_data = {}
if user_id_for_tokens:
# Single user stats
monthly_transcription = transcription_tracker.get_monthly_usage(user_id_for_tokens)
monthly_cost = transcription_tracker.get_monthly_cost(user_id_for_tokens)
user = db.session.get(User, user_id_for_tokens)
transcription_budget = user.monthly_transcription_budget if user else None
transcription_data = {
'used_this_month_seconds': monthly_transcription,
'used_this_month_minutes': monthly_transcription // 60,
'budget_seconds': transcription_budget,
'budget_minutes': transcription_budget // 60 if transcription_budget else None,
'percentage': round((monthly_transcription / transcription_budget * 100), 1) if transcription_budget else None,
'estimated_cost': round(monthly_cost, 4)
}
else:
# Aggregate all users (admin scope)
current_year = date.today().year
current_month = date.today().month
total_seconds = db.session.query(func.sum(TranscriptionUsage.audio_duration_seconds)).filter(
extract('year', TranscriptionUsage.date) == current_year,
extract('month', TranscriptionUsage.date) == current_month
).scalar() or 0
total_cost = db.session.query(func.sum(TranscriptionUsage.estimated_cost)).filter(
extract('year', TranscriptionUsage.date) == current_year,
extract('month', TranscriptionUsage.date) == current_month
).scalar() or 0
transcription_data = {
'used_this_month_seconds': total_seconds,
'used_this_month_minutes': total_seconds // 60,
'budget_seconds': None,
'budget_minutes': None,
'percentage': None,
'estimated_cost': round(total_cost, 4)
}
# Recent activity
today_start = datetime.combine(date.today(), datetime.min.time())
recordings_today = Recording.query.filter(
recording_filter,
Recording.created_at >= today_start
).count()
# Last completed transcription
last_completed = Recording.query.filter(
recording_filter,
Recording.status == 'COMPLETED',
Recording.completed_at.isnot(None)
).order_by(Recording.completed_at.desc()).first()
last_transcription = last_completed.completed_at.isoformat() if last_completed and last_completed.completed_at else None
# Build response
response = {
'recordings': {
'total': total,
'completed': completed,
'processing': processing,
'pending': pending,
'failed': failed
},
'storage': {
'used_bytes': storage_bytes,
'used_human': format_bytes(storage_bytes)
},
'queue': {
'jobs_queued': jobs_queued,
'jobs_processing': jobs_processing
},
'tokens': tokens_data,
'transcription': transcription_data,
'activity': {
'recordings_today': recordings_today,
'last_transcription': last_transcription
}
}
# Add user counts for admin scope
if scope == 'all' and current_user.is_admin:
total_users = User.query.count()
# Active = users with recordings in last 30 days
cutoff = datetime.utcnow() - timedelta(days=30)
active_users = db.session.query(func.count(func.distinct(Recording.user_id))).filter(
Recording.created_at >= cutoff
).scalar() or 0
response['users'] = {
'total': total_users,
'active': active_users
}
return jsonify(response)
# =============================================================================
# Current User
# =============================================================================
@api_v1_bp.route('/tokens/current', methods=['GET'])
@require_scope()
@login_required
def get_current_token():
"""The API token of this request: id, name, scopes and times (mailr spec G1)."""
from flask import g
from src.utils.token_auth import current_api_token
token = current_api_token()
if token is None:
return jsonify({'error': translate('server.apiError.no_api_token'), 'code': 'not_found'}), 404
def _z(dt):
return dt.isoformat(timespec='microseconds') + 'Z' if dt else None
return jsonify({
'id': token.id,
'name': token.name,
'scopes': token.scope_list,
'created_at': _z(token.created_at),
'expires_at': _z(token.expires_at),
'last_used_at': _z(token.last_used_at),
'via': 'query' if g.get('api_token_via_query') else 'header',
})
# Features this server supports (mailr spec G1). A key appears when the feature
# ships; a missing key means false.
CAPABILITY_FEATURES = {
'token_scopes': True,
'storage_quota': True,
'changes_feed': True,
'etags': True,
'webhook_signature_v2': True,
'external_refs': True,
'upload_idempotency': True,
'share_links': True,
'chat_sources': True,
}
# search: {'keyword': True, 'semantic': <Inquire on>} is filled in get_capabilities.
@api_v1_bp.route('/capabilities', methods=['GET'])
@require_scope()
@login_required
def get_capabilities():
"""Feature discovery for API clients; read this instead of the version string."""
from src.config.version import get_version
features = dict(CAPABILITY_FEATURES)
features['internal_sharing'] = os.environ.get('ENABLE_INTERNAL_SHARING', 'false').lower() == 'true'
features['public_sharing'] = os.environ.get('ENABLE_PUBLIC_SHARING', 'true').lower() == 'true'
features['can_share_publicly'] = bool(features['public_sharing'] and getattr(current_user, 'can_share_publicly', True))
from src.services.search_v1 import semantic_available
features['search'] = {'keyword': True, 'semantic': semantic_available()}
features['inquire'] = {
'enabled': os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() == 'true',
'agent': os.environ.get('ENABLE_INQUIRE_AGENT', 'false').lower() == 'true',
}
return jsonify({
'speakr_version': get_version(),
'api_version': '1.1',
'features': features,
# True only when the administrator states that the text, chat and
# embedding endpoints all run on machines they control.
'models_local': os.environ.get('MODELS_ARE_LOCAL', 'false').lower() == 'true',
})
@api_v1_bp.route('/users/me', methods=['GET'])
@require_scope('read')
@login_required
def get_current_user():
"""
Return the authenticated user's profile.
Companion apps and automation flows need a way to display the current
user's identity (issue #281). This endpoint returns a stable subset of the
profile and preferences fields plus the user's group memberships.
"""
memberships = []
for membership in (current_user.group_memberships or []):
if membership.group is None:
continue
memberships.append({
'group_id': membership.group_id,
'group_name': membership.group.name,
'role': membership.role,
'joined_at': membership.joined_at.isoformat() if membership.joined_at else None,
})
return jsonify({
'id': current_user.id,
'username': current_user.username,
'email': current_user.email,
'name': current_user.name,
'job_title': current_user.job_title,
'company': current_user.company,
'is_admin': bool(current_user.is_admin),
'email_verified': bool(current_user.email_verified),
'sso_provider': current_user.sso_provider,
'can_share_publicly': bool(current_user.can_share_publicly),
'preferences': {
'ui_language': current_user.ui_language,
'transcription_language': current_user.transcription_language,
'output_language': current_user.output_language,
'extract_events': bool(current_user.extract_events),
'auto_speaker_labelling': bool(current_user.auto_speaker_labelling),
'auto_speaker_labelling_threshold': current_user.auto_speaker_labelling_threshold,
# None means enabled, as in processing (#412 audit S10).
'auto_summarization': current_user.auto_summarization is not False,
'show_timestamps_simple_view': bool(current_user.show_timestamps_simple_view),
'editor_autosave': bool(current_user.editor_autosave),
'notify_email_on_completion': bool(current_user.notify_email_on_completion),
# The per-user diarize preference has had no control since Aug 2025
# and was never read; report what transcription actually does.
'diarize': _effective_diarize(),
},
'group_memberships': memberships,
# Storage used and the quota, NULL when there is none (#413). An upload
# over the quota is refused with 507 and code storage_quota_exceeded.
'storage': _storage_usage_for_api(current_user),
})
def _storage_usage_for_api(user):
from src.services.storage_quota import usage
u = usage(user)
return {'used_bytes': u['used_bytes'], 'quota_bytes': u['quota_bytes'],
'available_bytes': u['available_bytes']}
# =============================================================================
# Recordings List with Enhanced Filtering
# =============================================================================
def _updated_at_z(recording):
from src.services.recording_changes import effective_updated_at, iso_z
return iso_z(effective_updated_at(recording))
def _recording_list_item(r, refs=None, shared=None):
"""One recording as GET /recordings lists it; the changes feed uses the same shape.
refs: this caller's external references of the recording, when the caller
loaded them for a whole page (refs_map); otherwise read here.
"""
if refs is None:
from src.services.external_refs import refs_for
refs = [x.to_dict() for x in refs_for(r.id, current_user.id)]
from src.services.recording_changes import effective_updated_at, iso_z
return {
'id': r.id,
'title': r.title,
'status': r.status,
'created_at': r.created_at.isoformat() if r.created_at else None,
'completed_at': r.completed_at.isoformat() if r.completed_at else None,
'meeting_date': r.meeting_date.isoformat() if r.meeting_date else None,
'file_size': r.file_size,
'original_filename': r.original_filename,
'participants': r.participants,
'is_inbox': r.is_inbox,
'is_highlighted': r.is_highlighted,
'is_archived': bool(r.is_archived),
'audio_available': r.audio_deleted_at is None,
'audio_duration': r.get_audio_duration(),
'has_transcription': bool(r.transcription),
'has_summary': bool(r.summary),
'processing_time_seconds': r.processing_time_seconds,
'transcription_duration_seconds': r.transcription_duration_seconds,
'summarization_duration_seconds': r.summarization_duration_seconds,
'folder_id': r.folder_id,
'folder': {'id': r.folder.id, 'name': r.folder.name} if r.folder else None,
'deletion_exempt': r.deletion_exempt,
'error_message': r.error_message if r.status == 'FAILED' else None,
'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in r.tags],
'keep_audio_only': r.keep_audio_only,
'updated_at': iso_z(effective_updated_at(r)),
'external_refs': refs,
'is_shared': False,
'owner': None,
'share': None,
} if shared is None else dict(_recording_list_item(r, refs), **shared)
@api_v1_bp.route('/recordings', methods=['GET'])
@require_scope('read')
@login_required
def list_recordings():
"""
List recordings with filtering and pagination.
Query params:
page: Page number (default: 1)
per_page: Items per page (default: 25, max: 100)
status: Filter by status (pending, processing, completed, failed, all)
sort_by: Sort field (created_at, meeting_date, title, file_size, status)
sort_order: asc or desc (default: desc)
date_from: Filter from date (ISO format)
date_to: Filter to date (ISO format)
tag_id: Filter by tag ID
q: Search query (title, participants)
inbox: Filter by inbox status (true/false)
starred: Filter by starred status (true/false)
archived: Filter by archive status (true/false); omitted returns both
scope: own (default), shared or all
owner_id: Only recordings of this owner
updated_since: Only recordings changed after this time (ISO 8601)
date_field: What date_from and date_to filter: created_at (default)
or meeting_date
"""
# Parse query parameters
page = request.args.get('page', 1, type=int)
per_page = min(request.args.get('per_page', 25, type=int), 100)
status_filter = request.args.get('status', 'all').lower()
sort_by = request.args.get('sort_by', 'created_at')
sort_order = request.args.get('sort_order', 'desc').lower()
date_from = request.args.get('date_from')
date_to = request.args.get('date_to')
tag_id = request.args.get('tag_id', type=int)
folder_filter = request.args.get('folder_id', '').strip()
search_query = request.args.get('q', '').strip()
inbox_filter = request.args.get('inbox')
starred_filter = request.args.get('starred')
archived_filter = request.args.get('archived')
updated_since = request.args.get('updated_since')
from src.services.recording_scope import SCOPES, join_personal_state, personal_flag, scope_condition
scope = request.args.get('scope', 'own')
if scope not in SCOPES:
return jsonify({'error': translate('server.apiError.invalid_scope'), 'code': 'invalid_parameter'}), 400
owner_id = request.args.get('owner_id', type=int)
date_field = request.args.get('date_field', 'created_at')
if date_field not in ('created_at', 'meeting_date'):
return jsonify({'error': translate('server.apiError.invalid_date_field'),
'code': 'invalid_parameter'}), 400
# Base query - user's recordings.
# Eager-load folder and tag-association+Tag so the list builder
# doesn't trigger one lazy SELECT per row for folder access (25
# rows -> 25 extra queries) and one per tag association (another
# ~50 queries on a typical page). This collapses ~75 queries into
# the single paginated SELECT plus two joined-table joins.
from sqlalchemy.orm import joinedload
from src.models.organization import RecordingTag
query = (
Recording.query
.options(
joinedload(Recording.folder),
joinedload(Recording.tag_associations).joinedload(RecordingTag.tag),
)
.filter(scope_condition(current_user.id, scope))
)
if scope != 'own':
query = join_personal_state(query, current_user.id)
if owner_id is not None:
query = query.filter(Recording.user_id == owner_id)
# Status filter
if status_filter == 'pending':
query = query.filter(Recording.status == 'PENDING')
elif status_filter == 'processing':
query = query.filter(Recording.status.in_(['PROCESSING', 'SUMMARIZING']))
elif status_filter == 'completed':
query = query.filter(Recording.status == 'COMPLETED')
elif status_filter == 'failed':
query = query.filter(Recording.status == 'FAILED')
# 'all' = no status filter
# Date filters
# Aware values are converted to the naive-UTC storage convention; a bare
# date_to includes that whole day (#412 B8).
from src.utils.dates import to_utc_naive
date_column = Recording.meeting_date if date_field == 'meeting_date' else Recording.created_at
if date_from:
try:
from_date = to_utc_naive(datetime.fromisoformat(date_from.replace('Z', '+00:00')))
query = query.filter(date_column >= from_date)
except ValueError:
pass
if date_to:
try:
to_date = to_utc_naive(datetime.fromisoformat(date_to.replace('Z', '+00:00')))
if len(date_to.strip()) == 10:
query = query.filter(date_column < to_date + timedelta(days=1))
else:
query = query.filter(date_column <= to_date)
except ValueError:
pass
# External references (mailr spec G8): only the caller's own.
external_system = request.args.get('external_system')
external_ref = request.args.get('external_ref')
if external_system or external_ref:
if not (external_system and external_ref):
return jsonify({'error': translate('server.apiError.external_ref_pair_required'),
'code': 'invalid_parameter'}), 400
from src.models import RecordingExternalRef
ref_query = db.session.query(RecordingExternalRef.recording_id).filter(
RecordingExternalRef.user_id == current_user.id,
RecordingExternalRef.system == external_system,
RecordingExternalRef.ref == external_ref)
if request.args.get('external_kind'):
ref_query = ref_query.filter(RecordingExternalRef.kind == request.args['external_kind'])
query = query.filter(Recording.id.in_(ref_query))
changed_column = db.func.coalesce(Recording.updated_at, Recording.created_at)
if updated_since:
try:
since = to_utc_naive(datetime.fromisoformat(updated_since.replace('Z', '+00:00')))
except ValueError:
return jsonify({'error': translate('server.apiError.invalid_updated_since'),
'code': 'invalid_parameter'}), 400
query = query.filter(changed_column > since)
# Tag filter
if tag_id:
query = query.join(RecordingTag).filter(RecordingTag.tag_id == tag_id)
# Folder filter. Accepts an integer folder id, or the literal "none" to
# return recordings that are not in any folder. Anything else is ignored.
if folder_filter:
if folder_filter.lower() == 'none':
query = query.filter(Recording.folder_id.is_(None))
else:
try:
folder_id_int = int(folder_filter)
query = query.filter(Recording.folder_id == folder_id_int)
except ValueError:
pass
# Search filter
if search_query:
from src.utils.search import LIKE_ESCAPE, contains_pattern
search_pattern = contains_pattern(search_query)
query = query.filter(
or_(
Recording.title.ilike(search_pattern, escape=LIKE_ESCAPE),
Recording.participants.ilike(search_pattern, escape=LIKE_ESCAPE)
)
)
# Inbox and starred filters: the caller's own value (a recipient's is on
# SharedRecordingState).
if inbox_filter is not None:
is_inbox = inbox_filter.lower() == 'true'
query = query.filter((personal_flag(current_user.id, 'is_inbox', True) if scope != 'own'
else Recording.is_inbox) == is_inbox)
if starred_filter is not None:
is_starred = starred_filter.lower() == 'true'
query = query.filter((personal_flag(current_user.id, 'is_highlighted', False) if scope != 'own'
else Recording.is_highlighted) == is_starred)
# Archive filter (#394). The API keeps returning archived recordings by
# default so existing integrations see no change.
if archived_filter is not None:
is_archived = archived_filter.lower() == 'true'
query = query.filter((personal_flag(current_user.id, 'is_archived', False) if scope != 'own'
else db.func.coalesce(Recording.is_archived, False)) == is_archived)
# Sorting
sort_columns = {
'created_at': Recording.created_at,
'meeting_date': Recording.meeting_date,
'title': Recording.title,
'file_size': Recording.file_size,
'status': Recording.status,
'updated_at': changed_column,
}
sort_column = sort_columns.get(sort_by, Recording.created_at)
if sort_order == 'asc':
query = query.order_by(sort_column.asc())
else:
query = query.order_by(sort_column.desc())
# Pagination
pagination = query.paginate(page=page, per_page=per_page, error_out=False)
# Build response
from src.services.external_refs import refs_map
from src.services.recording_scope import share_details
page_refs = refs_map([r.id for r in pagination.items], current_user.id)
page_shared = share_details(pagination.items, current_user)
recordings = [_recording_list_item(r, page_refs.get(r.id, []), page_shared.get(r.id))
for r in pagination.items]
return jsonify({
'recordings': recordings,
'pagination': {
'page': pagination.page,
'per_page': pagination.per_page,
'total': pagination.total,
'total_pages': pagination.pages,
'has_next': pagination.has_next,
'has_prev': pagination.has_prev
}
})
# =============================================================================
# Recording Detail
# =============================================================================
def _conditional(prefix):
"""Weak ETag and If-None-Match for a GET on one recording (mailr spec G11).
The tag holds the recording id, its updated_at and a hash of the body, so
it also changes when something outside the recording changes the answer
(a tag or folder name, the viewer's transcript template, voice
suggestions). It runs after the view, so the view's access check comes
first and a caller without access gets 403 or 404, never 304.
"""
def decorator(view):
@wraps(view)
def wrapper(recording_id, *args, **kwargs):
import hashlib
from flask import make_response
from src.services.recording_changes import etag_matches, updated_at_us
response = make_response(view(recording_id, *args, **kwargs))
if response.status_code != 200 or response.direct_passthrough:
return response
recording = db.session.get(Recording, recording_id)
digest = hashlib.sha1(response.get_data()).hexdigest()[:16]
etag = f'W/"{prefix}{recording_id}-{updated_at_us(recording) if recording else 0}-{digest}"'
if etag_matches(request, etag):
response = make_response('', 304)
response.headers['ETag'] = etag
response.headers['Cache-Control'] = 'private, no-cache'
return response
return wrapper
return decorator
@api_v1_bp.route('/search', methods=['GET'])
@require_scope('read')
@rate_limit(os.environ.get('API_SEARCH_RATE_LIMIT', '30 per minute'), key_func=token_rate_key)
@login_required
def search_recordings_v1():
"""Search titles, participants, notes, summaries and transcripts (mailr spec G3).
Query params: q (2 to 500 characters), mode (keyword | semantic | auto),
fields, scope (own), recording_ids, tag_id, folder_id, speaker,
date_from, date_to, date_field (meeting_date | created_at), limit (1-50),
page (keyword mode).
"""
from src.services import search_v1
args = request.args
q = (args.get('q') or '').strip()
if not 2 <= len(q) <= 500:
return jsonify({'error': translate('server.apiError.invalid_query_length'), 'code': 'invalid_parameter'}), 400
mode = args.get('mode', 'keyword')
if mode not in ('keyword', 'semantic', 'auto'):
return jsonify({'error': translate('server.apiError.invalid_search_mode'), 'code': 'invalid_parameter'}), 400
scope = args.get('scope', 'own')
if scope not in ('own', 'shared', 'all'):
return jsonify({'error': translate('server.apiError.invalid_scope'), 'code': 'invalid_parameter'}), 400
fields = tuple(f.strip() for f in args.get('fields', ','.join(search_v1.FIELDS)).split(',') if f.strip())
unknown = [f for f in fields if f not in search_v1.FIELDS]
if unknown or not fields:
message = (translate('server.apiError.unknown_fields', fields=', '.join(unknown)) if unknown
else translate('server.apiError.no_fields_given'))
return jsonify({'error': message, 'code': 'invalid_parameter'}), 400
date_field = args.get('date_field', 'meeting_date')
if date_field not in ('meeting_date', 'created_at'):
return jsonify({'error': translate('server.apiError.invalid_date_field'), 'code': 'invalid_parameter'}), 400
limit = args.get('limit', 20, type=int)
page = args.get('page', 1, type=int)
if limit is None or not 1 <= limit <= 50 or page is None or page < 1:
return jsonify({'error': translate('server.apiError.invalid_search_paging'), 'code': 'invalid_parameter'}), 400
try:
recording_ids = [int(x) for x in args.get('recording_ids', '').split(',') if x.strip()] or None
except ValueError:
return jsonify({'error': translate('server.apiError.invalid_recording_ids_csv'), 'code': 'invalid_parameter'}), 400
folder = args.get('folder_id', '').strip()
folder_id = None
if folder:
if folder.lower() == 'none':
folder_id = 'none'
elif folder.isdigit():
folder_id = int(folder)
else:
return jsonify({'error': translate('server.apiError.invalid_folder_id'), 'code': 'invalid_parameter'}), 400
filters = dict(recording_ids=recording_ids, tag_id=args.get('tag_id', type=int), folder_id=folder_id,
date_from=args.get('date_from') or None, date_to=args.get('date_to') or None,
date_field=date_field, scope=scope)
speaker = (args.get('speaker') or '').strip() or None
use_semantic = mode == 'semantic' or (mode == 'auto' and search_v1.semantic_available())
if mode == 'semantic' and not search_v1.semantic_available():
return jsonify({'error': translate('server.apiError.semantic_search_unavailable'),
'code': 'semantic_unavailable'}), 409
try:
if use_semantic:
# The dates are checked the same way in both modes.
search_v1.candidate_query(current_user, ['x'], ('title',), **filters)
results = search_v1.semantic_search(current_user, q, limit=limit, speaker=speaker, **filters)
has_more = False
else:
results, has_more = search_v1.keyword_search(current_user, q, fields=fields, speaker=speaker,
limit=limit, page=page, **filters)
except search_v1.SearchError as e:
return jsonify({'error': str(e), 'code': e.code}), e.status
return jsonify({'query': q, 'mode_used': 'semantic' if use_semantic else 'keyword',
'results': results, 'page': page if not use_semantic else 1, 'has_more': has_more})
def _ref_recording(recording_id, require_edit):
recording = db.session.get(Recording, recording_id)
if not recording:
return None, (jsonify({'error': translate('server.apiError.recording_not_found'), 'code': 'not_found'}), 404)
if not has_recording_access(recording, current_user, require_edit=require_edit):
return None, (jsonify(api_error('permission_denied')), 403)
return recording, None
@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['GET'])
@require_scope('read')
@login_required
def list_external_refs(recording_id):
"""Your external references on a recording (mailr spec G8)."""
from src.services.external_refs import refs_for
recording, err = _ref_recording(recording_id, require_edit=False)
if err:
return err
return jsonify({'external_refs': [r.to_dict() for r in refs_for(recording.id, current_user.id)]})
@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['POST'])
@require_scope('write')
@login_required
def add_external_ref(recording_id):
"""Add one reference; an existing (system, kind, ref) answers 200 with it."""
from src.services import external_refs as xr
recording, err = _ref_recording(recording_id, require_edit=True)
if err:
return err
try:
row, created = xr.add(recording, current_user.id, xr.validate(request.get_json(silent=True)))
except xr.RefError as e:
return jsonify({'error': str(e), 'code': e.code}), e.status
db.session.commit()
return jsonify(row.to_dict()), 201 if created else 200
@api_v1_bp.route('/recordings/<int:recording_id>/external-refs', methods=['PUT'])
@require_scope('write')
@login_required
def replace_external_refs(recording_id):
"""Replace your references of one system (?system=) with the given list."""
from src.services import external_refs as xr
recording, err = _ref_recording(recording_id, require_edit=True)
if err:
return err
system = request.args.get('system', '')
body = request.get_json(silent=True) or {}
try:
if not xr._SLUG.match(system):
raise xr.RefError('?system= is required')
xr.replace_system(recording, current_user.id, system, xr.validate_list(body.get('external_refs')))
except xr.RefError as e:
db.session.rollback()
return jsonify({'error': str(e), 'code': e.code}), e.status
db.session.commit()
return jsonify({'external_refs': [r.to_dict() for r in xr.refs_for(recording.id, current_user.id)]})
@api_v1_bp.route('/recordings/<int:recording_id>/external-refs/<int:ref_id>', methods=['DELETE'])
@require_scope('write')
@login_required
def delete_external_ref(recording_id, ref_id):
from src.models import RecordingExternalRef
recording, err = _ref_recording(recording_id, require_edit=True)
if err:
return err
row = db.session.get(RecordingExternalRef, ref_id)
if row is None or row.recording_id != recording.id or row.user_id != current_user.id:
return jsonify({'error': translate('server.apiError.reference_not_found'), 'code': 'not_found'}), 404
db.session.delete(row)
db.session.commit()
return '', 204
@api_v1_bp.route('/recordings/<int:recording_id>/share', methods=['POST'])
@require_scope('share')
@login_required
def create_public_share(recording_id):
"""Create or reuse a public link (mailr spec G10). Notes are not shared
unless asked, and a reused link's flags change only with update_existing."""
from flask import url_for
from src.services.public_shares import get_or_create, share_dict
if os.environ.get('ENABLE_PUBLIC_SHARING', 'true').lower() != 'true':
return jsonify({'error': translate('server.apiError.public_sharing_off'), 'code': 'feature_disabled'}), 403
if not getattr(current_user, 'can_share_publicly', True):
return jsonify({'error': translate('server.apiError.public_link_not_permitted'), 'code': 'not_permitted'}), 403
if not request.is_secure:
return jsonify({'error': translate('server.apiError.public_link_https_required'), 'code': 'https_required'}), 403
recording = db.session.get(Recording, recording_id)
if not recording or recording.user_id != current_user.id:
return jsonify({'error': translate('server.apiError.recording_not_found'), 'code': 'not_found'}), 404
data = request.get_json(silent=True) or {}
flags = {}
for key, default in (('share_summary', True), ('share_notes', False), ('force_new', False),
('update_existing', False)):
value = data.get(key, default)
if not isinstance(value, bool):
return jsonify({'error': translate('server.apiError.invalid_boolean_flag', key=key),
'code': 'invalid_parameter'}), 400
flags[key] = value
days = data.get('expires_in_days')
if days is not None and (not isinstance(days, int) or isinstance(days, bool) or not 1 <= days <= 3650):
return jsonify({'error': translate('server.apiError.invalid_expires_in_days_range'), 'code': 'invalid_parameter'}), 400
share, created, differ = get_or_create(recording, current_user, flags['share_summary'], flags['share_notes'],
force_new=flags['force_new'], update_existing=flags['update_existing'],
expires_in_days=days)
return jsonify({
'share_url': url_for('shares.view_shared_recording', public_id=share.public_id, _external=True),
'existing': not created,
'flags_differ': differ,
'share': share_dict(share),
}), 201 if created else 200
@api_v1_bp.route('/recordings/<int:recording_id>/shares', methods=['GET'])
@require_scope('share')
@login_required
def list_public_shares(recording_id):
"""Your public links of a recording."""
from flask import url_for
from src.models import Share
from src.services.public_shares import share_dict
recording = db.session.get(Recording, recording_id)
if not recording or recording.user_id != current_user.id:
return jsonify({'error': translate('server.apiError.recording_not_found'), 'code': 'not_found'}), 404
shares = (Share.query.filter_by(recording_id=recording.id, user_id=current_user.id)
.order_by(Share.created_at.desc()).all())
return jsonify({'shares': [dict(share_dict(s), share_url=url_for('shares.view_shared_recording',
public_id=s.public_id, _external=True))
for s in shares]})
@api_v1_bp.route('/shares/<int:share_id>', methods=['DELETE'])
@require_scope('share')
@login_required
def revoke_public_share(share_id):
from src.models import Share
from src.services.public_shares import revoke
share = db.session.get(Share, share_id)
if share is None or share.user_id != current_user.id:
return jsonify({'error': translate('server.apiError.share_not_found'), 'code': 'not_found'}), 404
revoke(share)
return '', 204
@api_v1_bp.route('/recordings/changes', methods=['GET'])
@require_scope('read')
@login_required
def list_recording_changes():
"""Changes to the user's recordings since a cursor (mailr spec G2).
Query params:
cursor: from a previous answer; absent starts a full pass (every live
recording, no tombstones)
limit: 1 to 500 (default 100)
scope: own (default; shared and all arrive with G4)
"""
from src.services.recording_changes import (CursorError, cursor_expired, decode_cursor,
iso_z, read_changes)
cursor = request.args.get('cursor') or None
limit = request.args.get('limit', 100, type=int)
if limit is None or not 1 <= limit <= 500:
return jsonify({'error': translate('server.apiError.invalid_limit'), 'code': 'invalid_parameter'}), 400
scope = request.args.get('scope', 'own')
if scope not in ('own', 'shared', 'all'):
return jsonify({'error': translate('server.apiError.invalid_scope'), 'code': 'invalid_parameter'}), 400
if cursor:
try:
changed_at, _, _, full_since = decode_cursor(cursor)
except CursorError:
return jsonify({'error': translate('server.apiError.invalid_cursor'), 'code': 'invalid_parameter'}), 400
if cursor_expired(current_user.id, changed_at, full_since):
return jsonify({'error': translate('server.apiError.cursor_expired'),
'code': 'cursor_expired'}), 410
items, next_cursor, has_more = read_changes(current_user.id, cursor=cursor, limit=limit, scope=scope)
from src.services.external_refs import refs_map
from src.services.recording_scope import share_details
upserts = [obj for kind, obj in items if kind == 'upsert']
page_refs = refs_map([obj.id for obj in upserts], current_user.id)
page_shared = share_details(upserts, current_user)
changes = []
for kind, obj in items:
if kind == 'upsert':
changes.append({'type': 'upsert', 'recording': _recording_list_item(
obj, page_refs.get(obj.id, []), page_shared.get(obj.id))})
else:
changes.append({'type': 'delete', 'id': obj.recording_id,
'deleted_at': iso_z(obj.deleted_at), 'reason': obj.reason})
return jsonify({'changes': changes, 'next_cursor': next_cursor, 'has_more': has_more})
@api_v1_bp.route('/recordings/<int:recording_id>', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('r')
def get_recording(recording_id):
"""
Get full recording details.
Query params:
include: Comma-separated fields to include (transcription, summary, notes)
Default: all fields
format: 'full' (default) or 'minimal' (excludes large text fields)
"""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
from src.services.recording_changes import effective_updated_at, iso_z
include = request.args.get('include', 'transcription,summary,notes')
include_fields = [f.strip() for f in include.split(',')]
format_type = request.args.get('format', 'full')
response = {
'id': recording.id,
'title': recording.title,
'status': recording.status,
'participants': recording.participants,
'created_at': recording.created_at.isoformat() if recording.created_at else None,
'meeting_date': recording.meeting_date.isoformat() if recording.meeting_date else None,
'completed_at': recording.completed_at.isoformat() if recording.completed_at else None,
'file_size': recording.file_size,
'original_filename': recording.original_filename,
'mime_type': recording.mime_type,
'is_inbox': recording.is_inbox,
'is_highlighted': recording.is_highlighted,
'is_archived': get_user_archived(recording, current_user),
'audio_available': recording.audio_deleted_at is None,
'audio_duration': recording.get_audio_duration(),
'processing_time_seconds': recording.processing_time_seconds,
'transcription_duration_seconds': recording.transcription_duration_seconds,
'summarization_duration_seconds': recording.summarization_duration_seconds,
'folder_id': recording.folder_id,
'folder': {'id': recording.folder.id, 'name': recording.folder.name} if recording.folder else None,
'deletion_exempt': recording.deletion_exempt,
'events': [e.api_dict() for e in recording.events] if hasattr(recording, 'events') else [],
'error_message': recording.error_message if recording.status == 'FAILED' else None,
'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in recording.tags],
'duplicate_info': recording.get_duplicate_info(),
'keep_audio_only': recording.keep_audio_only,
'updated_at': iso_z(effective_updated_at(recording)),
'external_refs': [x.to_dict() for x in __import__('src.services.external_refs', fromlist=['refs_for'])
.refs_for(recording.id, current_user.id)],
}
# Include large text fields based on params
if format_type != 'minimal':
if 'transcription' in include_fields:
# Format transcription using user's default template
response['transcription'] = format_transcription_with_template(
recording.transcription, current_user
) if recording.transcription else None
if 'summary' in include_fields:
response['summary'] = recording.summary
if 'notes' in include_fields:
response['notes'] = recording.get_user_notes(current_user)
return jsonify(response)
# =============================================================================
# Recording Transcript/Summary/Notes Individual Endpoints
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/transcript', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('t')
def get_transcript(recording_id):
"""
Get transcript in various formats.
Query params:
format: json (default), text, srt, vtt
"""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
if not recording.transcription:
return jsonify(api_error('no_transcription')), 404
format_type = request.args.get('format', 'json').lower()
if format_type == 'json':
# One documented shape whatever key set the transcript was stored
# with (mailr spec G12); optional window: start, end, max_segments.
from src.services.transcript_segments import canonical_segments, window
segments = canonical_segments(recording)
if segments is None:
return jsonify({'format': 'json', 'kind': 'plain', 'segments': [], 'raw': recording.transcription})
try:
start = request.args.get('start', type=float)
end = request.args.get('end', type=float)
max_segments = request.args.get('max_segments', type=int)
except ValueError:
start = end = max_segments = None
if max_segments is not None and max_segments < 1:
return jsonify({'error': translate('server.apiError.invalid_max_segments'), 'code': 'invalid_parameter'}), 400
body = {'format': 'json', 'kind': 'segments', 'duration': recording.get_audio_duration()}
if start is not None or end is not None or max_segments is not None:
segments, next_start = window(segments, start, end, max_segments)
if next_start is not None:
body['next_start'] = next_start
body['segments'] = segments
return jsonify(body)
elif format_type == 'text':
# Use user's default template for text format
formatted = format_transcription_with_template(recording.transcription, current_user)
return jsonify({
'format': 'text',
'content': formatted
})
elif format_type in ['srt', 'vtt']:
try:
segments = json.loads(recording.transcription)
lines = []
if format_type == 'vtt':
lines.append('WEBVTT')
lines.append('')
for i, seg in enumerate(segments, 1):
start = seg.get('start_time', seg.get('start', 0))
end = seg.get('end_time', seg.get('end', start + 1))
text = seg.get('sentence') or seg.get('text', '')
speaker = seg.get('speaker', '')
# Format timestamps
def fmt_time(seconds, use_comma=False):
h = int(seconds // 3600)
m = int((seconds % 3600) // 60)
s = int(seconds % 60)
ms = int((seconds - int(seconds)) * 1000)
sep = ',' if use_comma else '.'
return f"{h:02d}:{m:02d}:{s:02d}{sep}{ms:03d}"
if format_type == 'srt':
lines.append(str(i))
lines.append(f"{fmt_time(start, True)} --> {fmt_time(end, True)}")
else:
lines.append(f"{fmt_time(start)} --> {fmt_time(end)}")
if speaker:
lines.append(f"<v {speaker}>{text}")
else:
lines.append(text)
lines.append('')
return jsonify({
'format': format_type,
'content': '\n'.join(lines)
})
except (json.JSONDecodeError, TypeError):
return jsonify(api_error('subtitle_generation_failed')), 400
return jsonify(api_error('unknown_format', format=format_type)), 400
@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('s')
def get_summary(recording_id):
"""Get summary markdown."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
return jsonify({
'summary': recording.summary,
'has_summary': bool(recording.summary)
})
@api_v1_bp.route('/recordings/<int:recording_id>/notes', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('n')
def get_notes(recording_id):
"""Get notes markdown."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
# The owner's notes for the owner; a recipient's own personal notes otherwise.
notes = recording.get_user_notes(current_user)
return jsonify({
'notes': notes,
'has_notes': bool(notes)
})
# =============================================================================
# Recording Update Operations
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>', methods=['PATCH'])
@require_scope('write')
@login_required
def update_recording(recording_id):
"""
Update recording metadata, notes, or summary.
Request body (all fields optional):
{
"title": "Updated Title",
"participants": "Alice, Bob",
"notes": "Updated notes...",
"summary": "Updated summary...",
"meeting_date": "2024-01-15T09:00:00Z",
"is_inbox": false,
"is_highlighted": true,
"folder_id": 5 // or null to remove the recording from its folder
}
"""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
# `keep_audio_only` is set at upload time and dictates whether the
# processing pipeline retained the video stream. Allowing PATCH to
# mutate it after the fact would create a misleading record (the
# file was already processed one way or the other). Reject explicitly
# rather than silently dropping so misuse surfaces in client logs.
if 'keep_audio_only' in data:
return jsonify({
**api_error('keep_audio_only_immutable')
}), 400
# Update fields if provided
if 'title' in data:
if data['title'] != recording.title:
recording.title_source = 'user'
recording.title = data['title']
if 'participants' in data:
recording.participants = data['participants']
if 'notes' in data:
from src.services.recording_state import set_user_notes
set_user_notes(recording, current_user, data['notes'])
if 'summary' in data:
recording.summary = data['summary']
if 'meeting_date' in data:
try:
if data['meeting_date']:
# meeting_date is stored as naive UTC (like created_at): convert
# zone-aware input to UTC before storing
recording.meeting_date = to_utc_naive(datetime.fromisoformat(data['meeting_date'].replace('Z', '+00:00')))
else:
recording.meeting_date = None
except ValueError:
return jsonify(api_error('invalid_meeting_date')), 400
if 'is_inbox' in data:
recording.is_inbox = bool(data['is_inbox'])
if 'is_highlighted' in data:
recording.is_highlighted = bool(data['is_highlighted'])
if 'is_archived' in data:
archived = parse_archived_flag(data['is_archived'])
if archived is None:
return jsonify(api_error('invalid_is_archived')), 400
# Per user, like the web app: a shared editor archives it for
# themselves only (#394).
set_user_archived(recording, current_user, archived, commit=False)
if 'folder_id' in data:
new_folder_id = data['folder_id']
if new_folder_id is None:
recording.folder_id = None
else:
from src.models.organization import Folder, GroupMembership
target = db.session.get(Folder, new_folder_id)
if not target:
return jsonify(api_error('folder_id_not_found', folderId=new_folder_id)), 404
# Personal folders: must own. Group folders: must be a member.
if target.group_id is None:
if target.user_id != current_user.id:
return jsonify(api_error('target_folder_access_denied')), 403
else:
membership = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=target.group_id
).first()
if not membership:
return jsonify(api_error('target_folder_access_denied')), 403
recording.folder_id = new_folder_id
db.session.commit()
# recording.updated goes out from the change listener after the commit
# (src/services/recording_changes.py), the same for every write path.
return jsonify({
'success': True,
'recording': {
'id': recording.id,
'title': recording.title,
'participants': recording.participants,
'notes': recording.get_user_notes(current_user),
'summary': recording.summary,
'meeting_date': recording.meeting_date.isoformat() if recording.meeting_date else None,
'is_inbox': recording.is_inbox,
'is_highlighted': recording.is_highlighted,
'is_archived': get_user_archived(recording, current_user),
'folder_id': recording.folder_id,
'updated_at': _updated_at_z(recording),
}
})
@api_v1_bp.route('/recordings/<int:recording_id>/notes', methods=['PUT'])
@require_scope('write')
@login_required
def replace_notes(recording_id):
"""Replace notes entirely."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
# Notes are per user, as in the web app: a recipient with view access
# writes their personal notes, never the owner's.
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data or 'notes' not in data:
return jsonify(api_error('notes_field_required')), 400
from src.services.recording_state import set_user_notes
set_user_notes(recording, current_user, data['notes'])
db.session.commit()
return jsonify({'success': True, 'notes': recording.get_user_notes(current_user)})
@api_v1_bp.route('/recordings/<int:recording_id>/summary', methods=['PUT'])
@require_scope('write')
@login_required
def replace_summary(recording_id):
"""Replace summary entirely."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data or 'summary' not in data:
return jsonify(api_error('summary_field_required')), 400
recording.summary = data['summary']
db.session.commit()
return jsonify({'success': True, 'summary': recording.summary})
# =============================================================================
# Recording Delete
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>', methods=['DELETE'])
@require_scope('delete')
@login_required
def delete_recording(recording_id):
"""Delete a recording."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
# Check ownership (only owner can delete)
if recording.user_id != current_user.id:
return jsonify(api_error('delete_owner_only')), 403
# Check if deletion is allowed
USERS_CAN_DELETE = os.environ.get('USERS_CAN_DELETE', 'true').lower() == 'true'
if not USERS_CAN_DELETE and not current_user.is_admin:
return jsonify(api_error('deletion_not_allowed')), 403
# Same deletion as the web app: storage-aware media removal, snippets and
# jobs first (NOT NULL recording_id), webhook, export and speaker cleanup.
from src.services.recording_deletion import delete_recording_completely, cleanup_orphaned_speakers_quietly
try:
delete_recording_completely(recording)
except Exception as e:
db.session.rollback()
current_app.logger.error(f"API v1 delete failed for recording {recording_id}: {e}", exc_info=True)
return jsonify(api_error('recording_delete_failed')), 500
cleanup_orphaned_speakers_quietly()
return jsonify({'success': True, 'message': translate('server.apiMessage.recordingDeleted')})
@api_v1_bp.route('/recordings/<int:recording_id>/delete-audio', methods=['POST'])
@require_scope('delete')
@login_required
def delete_recording_audio(recording_id):
"""Delete a recording's media file and keep its transcript, summary and notes."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if recording.user_id != current_user.id:
return jsonify(api_error('delete_owner_only')), 403
USERS_CAN_DELETE = os.environ.get('USERS_CAN_DELETE', 'true').lower() == 'true'
if not USERS_CAN_DELETE and not current_user.is_admin:
return jsonify(api_error('deletion_not_allowed')), 403
if recording.audio_deleted_at:
return jsonify(api_error('audio_already_removed')), 409
if recording.status not in ('COMPLETED', 'FAILED'):
return jsonify(api_error('audio_remove_while_processing')), 409
from src.services.retention import remove_recording_audio
remove_recording_audio(recording)
return jsonify({'success': True, 'audio_deleted_at': recording.audio_deleted_at.isoformat()})
# =============================================================================
# Recording Status
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/status', methods=['GET'])
@require_scope('read')
@login_required
def get_recording_status(recording_id):
"""Get processing status of a recording."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
# Get queue position if pending/processing
queue_position = None
if recording.status in ['PENDING', 'PROCESSING', 'SUMMARIZING']:
# Count jobs ahead of this one
job = ProcessingJob.query.filter_by(
recording_id=recording_id,
status='queued'
).first()
if job:
queue_position = ProcessingJob.query.filter(
ProcessingJob.status == 'queued',
ProcessingJob.created_at < job.created_at
).count() + 1
return jsonify({
'id': recording.id,
'status': recording.status,
'queue_position': queue_position,
'error_message': recording.error_message if recording.status == 'FAILED' else None,
'completed_at': recording.completed_at.isoformat() if recording.completed_at else None
})
# =============================================================================
# Title Regeneration
# =============================================================================
def _effective_diarize():
"""Whether recordings are diarized: the active connector's default (the
processing task passes no per-user preference)."""
try:
from src.services.transcription import get_registry
connector = get_registry().get_active_connector()
return bool(connector.supports_diarization and connector.default_diarize)
except Exception:
return False
@api_v1_bp.route('/recordings/<int:recording_id>/regenerate_title', methods=['POST'])
@require_scope('process')
@login_required
def api_regenerate_title(recording_id):
"""Regenerate the AI title for a recording based on its existing transcription."""
from src.api.recordings import regenerate_title
return regenerate_title(recording_id)
# =============================================================================
# Tag Management
# =============================================================================
@api_v1_bp.route('/tags', methods=['GET'])
@require_scope('read')
@login_required
def list_tags():
"""List available tags (personal + group tags user has access to)."""
from src.models.organization import GroupMembership
# Get user's personal tags
user_tags = Tag.query.filter_by(user_id=current_user.id, group_id=None).order_by(Tag.name).all()
# Get user's team memberships
memberships = GroupMembership.query.filter_by(user_id=current_user.id).all()
team_roles = {m.group_id: m.role for m in memberships}
team_ids = list(team_roles.keys())
# Get group tags
team_tags = []
if team_ids:
team_tags = Tag.query.filter(Tag.group_id.in_(team_ids)).order_by(Tag.name).all()
result = []
# Personal tags
for tag in user_tags:
result.append({
'id': tag.id,
'name': tag.name,
'color': tag.color,
'is_group_tag': False,
'group_id': None,
'custom_prompt': tag.custom_prompt,
'title_prompt': tag.title_prompt,
'default_language': tag.default_language,
'default_min_speakers': tag.default_min_speakers,
'default_max_speakers': tag.default_max_speakers,
'protect_from_deletion': tag.protect_from_deletion,
'can_edit': True
})
# Group tags
for tag in team_tags:
user_role = team_roles.get(tag.group_id, 'member')
result.append({
'id': tag.id,
'name': tag.name,
'color': tag.color,
'is_group_tag': True,
'group_id': tag.group_id,
'custom_prompt': tag.custom_prompt,
'title_prompt': tag.title_prompt,
'default_language': tag.default_language,
'default_min_speakers': tag.default_min_speakers,
'default_max_speakers': tag.default_max_speakers,
'protect_from_deletion': tag.protect_from_deletion,
'can_edit': (user_role == 'admin')
})
name = (request.args.get('name') or '').strip().lower()
if name:
result = [t for t in result if (t['name'] or '').strip().lower() == name]
return jsonify({'tags': result})
@api_v1_bp.route('/tags', methods=['POST'])
@require_scope('write')
@login_required
def create_tag():
"""Create a new tag."""
from src.models.organization import GroupMembership
data = request.get_json()
if not data or not data.get('name'):
return jsonify(api_error('tag_name_required')), 400
group_id = data.get('group_id')
# If group tag, verify admin permission
if group_id:
membership = GroupMembership.query.filter_by(
group_id=group_id,
user_id=current_user.id
).first()
if not membership or membership.role != 'admin':
return jsonify(api_error('group_tag_create_admin_only')), 403
# Check for duplicate
existing = Tag.query.filter_by(name=data['name'], group_id=group_id).first()
if existing:
return jsonify(api_error('group_tag_name_exists_for_group')), 400
else:
# Check for duplicate personal tag
existing = Tag.query.filter_by(name=data['name'], user_id=current_user.id, group_id=None).first()
if existing:
return jsonify(api_error('tag_name_exists')), 400
tag = Tag(
name=data['name'],
user_id=current_user.id,
group_id=group_id,
color=data.get('color', '#3B82F6'),
custom_prompt=data.get('custom_prompt'),
title_prompt=data.get('title_prompt'),
default_language=data.get('default_language'),
default_min_speakers=data.get('default_min_speakers'),
default_max_speakers=data.get('default_max_speakers'),
protect_from_deletion=data.get('protect_from_deletion', False)
)
db.session.add(tag)
db.session.commit()
return jsonify({
'id': tag.id,
'name': tag.name,
'color': tag.color,
'is_group_tag': tag.group_id is not None,
'group_id': tag.group_id,
'custom_prompt': tag.custom_prompt,
'title_prompt': tag.title_prompt,
'default_language': tag.default_language,
'default_min_speakers': tag.default_min_speakers,
'default_max_speakers': tag.default_max_speakers,
'protect_from_deletion': tag.protect_from_deletion
}), 201
@api_v1_bp.route('/tags/<int:tag_id>', methods=['PUT'])
@require_scope('write')
@login_required
def update_tag(tag_id):
"""Update a tag."""
from src.models.organization import GroupMembership
tag = db.session.get(Tag, tag_id)
if not tag:
return jsonify(api_error('tag_not_found')), 404
# Check permission
if tag.group_id:
membership = GroupMembership.query.filter_by(
group_id=tag.group_id,
user_id=current_user.id
).first()
if not membership or membership.role != 'admin':
return jsonify(api_error('group_tag_edit_admin_only')), 403
else:
if tag.user_id != current_user.id:
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
if 'name' in data:
tag.name = data['name']
if 'color' in data:
tag.color = data['color']
if 'custom_prompt' in data:
tag.custom_prompt = data['custom_prompt']
if 'title_prompt' in data:
tag.title_prompt = data['title_prompt'] or None
if 'default_language' in data:
tag.default_language = data['default_language']
if 'default_min_speakers' in data:
tag.default_min_speakers = data['default_min_speakers']
if 'default_max_speakers' in data:
tag.default_max_speakers = data['default_max_speakers']
if 'protect_from_deletion' in data:
tag.protect_from_deletion = data['protect_from_deletion']
db.session.commit()
return jsonify({'success': True, 'tag': {
'id': tag.id,
'name': tag.name,
'color': tag.color,
'custom_prompt': tag.custom_prompt,
'title_prompt': tag.title_prompt,
'default_language': tag.default_language,
'default_min_speakers': tag.default_min_speakers,
'default_max_speakers': tag.default_max_speakers,
'protect_from_deletion': tag.protect_from_deletion
}})
@api_v1_bp.route('/tags/<int:tag_id>', methods=['DELETE'])
@require_scope('delete')
@login_required
def delete_tag(tag_id):
"""Delete a tag."""
from src.models.organization import GroupMembership
tag = db.session.get(Tag, tag_id)
if not tag:
return jsonify(api_error('tag_not_found')), 404
# Check permission
if tag.group_id:
membership = GroupMembership.query.filter_by(
group_id=tag.group_id,
user_id=current_user.id
).first()
if not membership or membership.role != 'admin':
return jsonify(api_error('group_tag_delete_admin_only')), 403
else:
if tag.user_id != current_user.id:
return jsonify(api_error('permission_denied')), 403
# Remove all recording associations
RecordingTag.query.filter_by(tag_id=tag_id).delete()
db.session.delete(tag)
db.session.commit()
return jsonify({'success': True, 'message': translate('server.apiMessage.tagDeleted')})
def _tag_problem(recording, tag):
"""Why the caller may not apply tag to recording, or None."""
from src.models.organization import GroupMembership
if tag is None:
return 'not found'
if tag.group_id:
membership = GroupMembership.query.filter_by(group_id=tag.group_id, user_id=current_user.id).first()
if not membership:
return 'no access'
if recording.user_id != current_user.id and membership.role != 'admin':
return 'only the recording owner or a group admin can apply group tags'
return None
return None if tag.user_id == current_user.id else 'no access'
def _share_scope_refusal(recording, tags):
"""403 when applying these tags would share the recording and the token
lacks the share scope (mailr spec section 8); nothing has changed yet."""
from src.services.tag_sharing import share_targets
from src.utils.token_auth import current_api_token, scope_error_response
token = current_api_token()
if token is None or token.scope_set is None or 'share' in token.scope_set:
return None
if any(share_targets(recording, tag) for tag in tags):
return scope_error_response({'share'}, token)
return None
@api_v1_bp.route('/recordings/<int:recording_id>/tags', methods=['POST'])
@require_scope('write')
@login_required
def add_tags_to_recording(recording_id):
"""Add tag(s) to a recording. Needs edit access; a group tag that shares
the recording also needs the share scope on a scoped token."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
data = request.get_json() or {}
tag_ids = data.get('tag_ids', [])
if not tag_ids:
# Support single tag_id for backward compatibility
tag_id = data.get('tag_id')
if tag_id:
tag_ids = [tag_id]
else:
return jsonify(api_error('tag_ids_required')), 400
errors = []
to_add = []
present = {rt.tag_id for rt in RecordingTag.query.filter_by(recording_id=recording_id)}
for tag_id in tag_ids:
tag = db.session.get(Tag, tag_id)
problem = _tag_problem(recording, tag)
if problem == 'not found':
errors.append(f'Tag {tag_id} not found')
elif problem:
errors.append(f'No access to tag {tag_id}')
elif tag.id not in present and tag not in to_add:
to_add.append(tag)
refusal = _share_scope_refusal(recording, to_add)
if refusal is not None:
return refusal
from src.services.tag_sharing import apply_tag_shares
max_order = db.session.query(func.max(RecordingTag.order)).filter_by(recording_id=recording_id).scalar() or 0
added_tags = []
for offset, tag in enumerate(to_add, 1):
db.session.add(RecordingTag(recording_id=recording_id, tag_id=tag.id, order=max_order + offset))
apply_tag_shares(recording, tag)
added_tags.append({'id': tag.id, 'name': tag.name})
db.session.commit()
return jsonify({
'success': True,
'added_tags': added_tags,
'errors': errors if errors else None
})
@api_v1_bp.route('/recordings/<int:recording_id>/tags', methods=['PUT'])
@require_scope('write')
@login_required
def replace_recording_tags(recording_id):
"""Set the recording's tags to exactly tag_ids, in that order.
Tags the caller cannot see (another user's personal tags) stay on the
recording. An unknown or forbidden id refuses the whole request.
"""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify({'error': translate('server.apiError.recording_not_found'), 'code': 'not_found'}), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
data = request.get_json(silent=True) or {}
tag_ids = data.get('tag_ids')
if not isinstance(tag_ids, list) or not all(isinstance(t, int) and not isinstance(t, bool) for t in tag_ids):
return jsonify({'error': translate('server.apiError.invalid_tag_ids_list'), 'code': 'invalid_parameter'}), 400
wanted, bad = [], []
for tag_id in dict.fromkeys(tag_ids):
tag = db.session.get(Tag, tag_id)
if _tag_problem(recording, tag):
bad.append(tag_id)
else:
wanted.append(tag)
if bad:
return jsonify({'error': translate('server.apiError.forbidden_tag_ids'), 'code': 'invalid_parameter',
'tag_ids': bad}), 400
visible = {t.id for t in recording.get_visible_tags(current_user)}
current = RecordingTag.query.filter_by(recording_id=recording_id).order_by(RecordingTag.order).all()
current_ids = [rt.tag_id for rt in current]
added = [t for t in wanted if t.id not in current_ids]
removed = [rt.tag_id for rt in current if rt.tag_id in visible and rt.tag_id not in {t.id for t in wanted}]
refusal = _share_scope_refusal(recording, added)
if refusal is not None:
return refusal
from src.services.tag_sharing import apply_tag_shares
for rt in current:
if rt.tag_id in removed:
db.session.delete(rt)
db.session.flush()
kept_hidden = [rt for rt in current if rt.tag_id not in visible]
by_id = {rt.tag_id: rt for rt in current if rt.tag_id not in removed}
order = 0
for tag in wanted:
order += 1
if tag.id in by_id:
if by_id[tag.id].order != order:
by_id[tag.id].order = order
else:
db.session.add(RecordingTag(recording_id=recording_id, tag_id=tag.id, order=order))
apply_tag_shares(recording, tag)
for rt in kept_hidden:
order += 1
rt.order = order
db.session.commit()
return jsonify({
'tags': [{'id': t.id, 'name': t.name, 'color': t.color} for t in wanted],
'added': [t.id for t in added],
'removed': removed,
})
@api_v1_bp.route('/recordings/<int:recording_id>/tags/<int:tag_id>', methods=['DELETE'])
@require_scope('write')
@login_required
def remove_tag_from_recording(recording_id, tag_id):
"""Remove a tag from a recording."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
recording_tag = RecordingTag.query.filter_by(
recording_id=recording_id,
tag_id=tag_id
).first()
if not recording_tag:
return jsonify(api_error('tag_not_on_recording')), 404
db.session.delete(recording_tag)
db.session.commit()
return jsonify({'success': True, 'message': translate('server.apiMessage.tagRemoved')})
# =============================================================================
# Folder Management
#
# These endpoints delegate to the existing web handlers in src/api/folders.py
# so permission semantics (group folders, member vs admin) match the web UI
# exactly. The web handlers already return jsonified, API-shaped responses
# (`folder.to_dict()` for success, `{"error": "..."}` for errors), so the
# delegation produces clean API output.
#
# Contract dependency: the v1 API's response shape on these routes is whatever
# the corresponding handler in folders.py returns. Changing those return
# shapes silently changes this API. A future cleanup should extract a
# services/folder.py layer that returns data dicts, with both the web and v1
# endpoints thin-wrapping with jsonify; that decouples the API contract from
# the web response framing.
# =============================================================================
@api_v1_bp.route('/folders', methods=['GET'])
@require_scope('read')
@login_required
def list_folders():
"""List folders the user can access (personal + group folders)."""
from src.api.folders import get_folders as _web_get_folders
return _web_get_folders()
@api_v1_bp.route('/folders', methods=['POST'])
@require_scope('write')
@login_required
def create_folder():
"""Create a new folder. Accepts the same JSON body as the web endpoint."""
from src.api.folders import create_folder as _web_create_folder
return _web_create_folder()
@api_v1_bp.route('/folders/<int:folder_id>', methods=['GET'])
@require_scope('read')
@login_required
def get_folder(folder_id):
"""Get a single folder by id."""
from src.models.organization import Folder, GroupMembership
folder = db.session.get(Folder, folder_id)
if not folder:
return jsonify(api_error('folder_not_found')), 404
# Personal folders: must own it. Group folders: must be a member.
if folder.group_id is None:
if folder.user_id != current_user.id:
return jsonify(api_error('permission_denied')), 403
else:
membership = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=folder.group_id
).first()
if not membership:
return jsonify(api_error('permission_denied')), 403
folder_dict = folder.to_dict()
if folder.group_id is None:
folder_dict['can_edit'] = True
else:
membership = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=folder.group_id
).first()
folder_dict['can_edit'] = bool(membership and membership.role == 'admin')
return jsonify(folder_dict)
@api_v1_bp.route('/folders/<int:folder_id>', methods=['PATCH', 'PUT'])
@require_scope('write')
@login_required
def update_folder(folder_id):
"""Update a folder. Same JSON body as the web endpoint."""
from src.api.folders import update_folder as _web_update_folder
return _web_update_folder(folder_id)
@api_v1_bp.route('/folders/<int:folder_id>', methods=['DELETE'])
@require_scope('delete')
@login_required
def delete_folder(folder_id):
"""Delete a folder. Recordings in it are unassigned."""
from src.api.folders import delete_folder as _web_delete_folder
return _web_delete_folder(folder_id)
# =============================================================================
# Transcription Connector & Model Discovery
# =============================================================================
@api_v1_bp.route('/transcription', methods=['GET'])
@require_scope('read')
@login_required
def get_transcription_info():
"""
Return information about the active transcription connector so API
clients can know which fields are accepted and which model values are
valid for `transcription_model` overrides.
Response shape:
{
"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"
}
"""
from src.models import SystemSetting
from src.config.app_config import (
TRANSCRIPTION_MODEL,
USE_NEW_TRANSCRIPTION_ARCHITECTURE,
USE_ASR_ENDPOINT,
)
connector_name = None
capabilities = {
'diarization': USE_ASR_ENDPOINT,
'speaker_count_control': USE_ASR_ENDPOINT,
'hotwords': USE_ASR_ENDPOINT,
'initial_prompt': USE_ASR_ENDPOINT,
'timestamps': True,
'language_detection': True,
'chunking': False,
}
connector = None
if USE_NEW_TRANSCRIPTION_ARCHITECTURE:
try:
from src.services.transcription import get_registry
registry = get_registry()
connector_name = registry.get_active_connector_name()
connector = registry.get_active_connector()
if connector:
capabilities = {
'diarization': connector.supports_diarization,
'speaker_count_control': connector.supports_speaker_count_control,
'hotwords': connector.supports_hotwords,
'initial_prompt': connector.supports_initial_prompt,
'timestamps': True,
'language_detection': True,
'chunking': connector.supports_chunking,
}
except Exception as e:
current_app.logger.warning(f"Could not read connector capabilities: {e}")
# Visible models: admin-curated DB list takes precedence over the
# TRANSCRIPTION_MODELS_AVAILABLE env var.
models = []
raw = SystemSetting.get_setting('transcription_models_visible_json', None)
if raw:
try:
parsed = json.loads(raw)
if isinstance(parsed, list):
for item in parsed:
if isinstance(item, dict) and item.get('value'):
models.append({
'value': item['value'],
'label': item.get('label') or item['value'],
})
elif isinstance(item, str) and item:
models.append({'value': item, 'label': item})
except Exception:
models = []
if not models:
# TRANSCRIPTION_MODELS_AVAILABLE paired with TRANSCRIPTION_MODEL_LABELS.
from src.config.app_config import TRANSCRIPTION_MODEL_OPTIONS
models = [dict(option) for option in TRANSCRIPTION_MODEL_OPTIONS]
# The model a transcription with no tag, folder or request choice uses:
# the admin default, else the connector's own configured model.
from src.services.transcription_defaults import resolve_transcription_model
default_model = (resolve_transcription_model(None)
or (getattr(connector, 'model', None) if connector else None)
or None)
return jsonify({
'connector': connector_name,
'capabilities': capabilities,
'models': models,
'default_model': default_model,
})
# =============================================================================
# Speaker Management
# =============================================================================
@api_v1_bp.route('/speakers', methods=['GET'])
@require_scope('read')
@login_required
def list_speakers():
"""List all speakers for the current user. ?email= filters by address."""
query = Speaker.query.filter_by(user_id=current_user.id)
email = (request.args.get('email') or '').strip().lower()
if email:
query = query.filter(db.func.lower(Speaker.email) == email)
speakers = query.order_by(Speaker.use_count.desc(), Speaker.last_used.desc()).all()
return jsonify({'speakers': [_speaker_item(s) for s in speakers]})
_EMAIL = re.compile(r'^[^@\s]+@[^@\s]+\.[^@\s]+$')
def _speaker_item(s):
try:
aliases = json.loads(s.aliases) if s.aliases else []
except (TypeError, ValueError):
aliases = []
changed = s.updated_at or s.created_at
return {
'id': s.id,
'name': s.name,
'use_count': s.use_count,
'last_used': s.last_used.isoformat() if s.last_used else None,
'confidence_score': s.confidence_score,
'has_voice_profile': s.average_embedding is not None,
'email': s.email,
'aliases': aliases if isinstance(aliases, list) else [],
'updated_at': changed.strftime('%Y-%m-%dT%H:%M:%S.%fZ') if changed else None,
}
def _speaker_contact_fields(data, speaker):
"""Apply email and aliases from a request body; returns the server.apiError
key of the problem, or None."""
if 'email' in data:
email = data['email']
if email is None or (isinstance(email, str) and not email.strip()):
speaker.email = None
elif isinstance(email, str) and len(email.strip()) <= 320 and _EMAIL.match(email.strip()):
speaker.email = email.strip().lower()
else:
return 'invalid_speaker_email'
if 'aliases' in data:
aliases = data['aliases']
if aliases is None:
aliases = []
if not isinstance(aliases, list) or not all(isinstance(a, str) for a in aliases):
return 'invalid_speaker_aliases'
clean, seen = [], set()
for alias in aliases:
alias = alias.strip()
if not alias:
continue
if len(alias) > 100:
return 'speaker_alias_too_long'
if alias.lower() not in seen:
seen.add(alias.lower())
clean.append(alias)
if len(clean) > 20:
return 'too_many_speaker_aliases'
speaker.aliases = json.dumps(clean) if clean else None
return None
@api_v1_bp.route('/speakers', methods=['POST'])
@require_scope('write')
@login_required
def create_speaker():
"""Create a new speaker (name, optional email and aliases)."""
data = request.get_json()
if not data or not data.get('name'):
return jsonify(api_error('speaker_name_required')), 400
name = data['name'].strip()
# Check if already exists
existing = Speaker.query.filter_by(user_id=current_user.id, name=name).first()
if existing:
return jsonify(api_error('speaker_name_taken')), 400
speaker = Speaker(
name=name,
user_id=current_user.id,
use_count=0,
created_at=datetime.utcnow()
)
problem = _speaker_contact_fields(data, speaker)
if problem:
return jsonify({'error': translate(f'server.apiError.{problem}'), 'code': 'invalid_parameter'}), 400
db.session.add(speaker)
db.session.commit()
item = _speaker_item(speaker)
item['created_at'] = speaker.created_at.isoformat()
return jsonify(item), 201
@api_v1_bp.route('/speakers/<int:speaker_id>', methods=['PUT'])
@require_scope('write')
@login_required
def update_speaker(speaker_id):
"""Update a speaker's name, email or aliases. A new name reaches every
recording the speaker appears in, as in Speaker Management."""
speaker = db.session.get(Speaker, speaker_id)
if not speaker:
return jsonify(api_error('speaker_not_found')), 404
if speaker.user_id != current_user.id:
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
problem = _speaker_contact_fields(data, speaker)
if problem:
db.session.rollback()
return jsonify({'error': translate(f'server.apiError.{problem}'), 'code': 'invalid_parameter'}), 400
renamed = {}
if 'name' in data:
new_name = (data.get('name') or '').strip()
if not new_name:
db.session.rollback()
return jsonify({'error': translate('server.apiError.speaker_name_empty'), 'code': 'invalid_parameter'}), 400
if new_name != speaker.name:
clash = Speaker.query.filter_by(user_id=current_user.id, name=new_name).first()
if clash and clash.id != speaker.id:
db.session.rollback()
return jsonify({'error': translate('server.apiError.speaker_name_exists', name=new_name),
'code': 'conflict'}), 409
from src.services.speaker_merge import rename_speaker_in_recordings
old_name = speaker.name
speaker.name = new_name
_, renamed = rename_speaker_in_recordings(current_user.id, old_name, new_name,
speaker_id=speaker.id, new_speaker_id=speaker.id)
elif not any(k in data for k in ('email', 'aliases')):
return jsonify({'error': translate('server.apiError.speaker_nothing_to_change'), 'code': 'invalid_parameter'}), 400
db.session.commit()
if renamed:
from src.services.speaker_merge import refresh_renamed_recordings
refresh_renamed_recordings(renamed)
return jsonify({'success': True, 'speaker': _speaker_item(speaker)})
@api_v1_bp.route('/speakers/<int:speaker_id>', methods=['DELETE'])
@require_scope('delete')
@login_required
def delete_speaker(speaker_id):
"""Delete a speaker."""
speaker = db.session.get(Speaker, speaker_id)
if not speaker:
return jsonify(api_error('speaker_not_found')), 404
if speaker.user_id != current_user.id:
return jsonify(api_error('permission_denied')), 403
db.session.delete(speaker)
db.session.commit()
return jsonify({'success': True, 'message': translate('server.apiMessage.speakerDeleted')})
@api_v1_bp.route('/recordings/<int:recording_id>/speakers', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('k')
def get_recording_speakers(recording_id):
"""Get speakers in a recording with suggestions."""
from src.services.speaker_embedding_matcher import find_matching_speakers
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
# One entry per person in the transcript: the diarization label (when
# known), the name it was given and the linked saved speaker. Email only
# for the speaker's owner (mailr spec G6).
from src.services.transcript_segments import canonical_segments
speakers_in_recording = []
entries = {}
is_owner = recording.user_id == current_user.id
owned = {}
for seg in canonical_segments(recording) or []:
named = seg['speaker'] if seg['speaker'] and seg['speaker'] != seg['speaker_label'] else None
key = seg['speaker_id'] or seg['speaker_label'] or seg['speaker'] or 'Unknown'
entry = entries.get(key)
if entry is None:
entry = entries[key] = {
'label': seg['speaker_label'] or seg['speaker'] or 'Unknown',
'identified_name': named,
'speaker_id': seg['speaker_id'],
'email': None,
'segment_count': 0,
}
speakers_in_recording.append(entry)
entry['segment_count'] += 1
if is_owner:
ids = [e['speaker_id'] for e in speakers_in_recording if e['speaker_id']]
if ids:
owned = {sp.id: sp for sp in Speaker.query.filter(Speaker.id.in_(ids), Speaker.user_id == current_user.id)}
for entry in speakers_in_recording:
if entry['speaker_id'] in owned:
entry['email'] = owned[entry['speaker_id']].email
# Get voice-based suggestions. speaker_embeddings maps each SPEAKER_XX
# label to one embedding (any dimension); find_matching_speakers takes a
# single embedding (plus user_id), compares it within the recording's
# embedding space and returns a sorted match list with similarity
# already expressed as a percentage.
suggestions = {}
if recording.speaker_embeddings:
try:
embeddings_data = (
json.loads(recording.speaker_embeddings)
if isinstance(recording.speaker_embeddings, str)
else recording.speaker_embeddings
)
from src.services.voice_profiles import suggestion_threshold
space_id = recording.speaker_embeddings_space_id
for label, embedding in embeddings_data.items():
if not embedding:
continue
matches = find_matching_speakers(embedding, current_user.id,
threshold=suggestion_threshold(space_id), space_id=space_id)
suggestions[label] = [{
'speaker_id': m['speaker_id'],
'name': m['name'],
'similarity': m['similarity']
} for m in matches[:3]]
except Exception as e:
current_app.logger.error(f"Error getting speaker suggestions: {e}")
return jsonify({
'speakers': speakers_in_recording,
'suggestions': suggestions
})
@api_v1_bp.route('/recordings/<int:recording_id>/speakers/assign', methods=['PUT'])
@require_scope('write')
@login_required
def assign_speakers(recording_id):
"""
Assign speaker names to a recording's transcription segments.
Accepts the same speaker_map format as the web UI, plus convenience
formats for API callers (plain strings).
Request body:
{
"speaker_map": {
"SPEAKER_00": "Jane Doe", // string shorthand
"SPEAKER_01": {"name": "Bob", "isMe": false} // full object
},
"regenerate_summary": false
}
"""
from src.services.speaker import update_speaker_usage
from src.services.job_queue import job_queue
try:
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
data = request.get_json()
if not data or 'speaker_map' not in data:
return jsonify(api_error('speaker_map_required')), 400
raw_speaker_map = data['speaker_map']
regenerate_summary = data.get('regenerate_summary', False)
if not isinstance(raw_speaker_map, dict):
return jsonify(api_error('invalid_speaker_map')), 400
# Normalize values to {name, isMe} format (same as web UI expects)
speaker_map = {}
for label, value in raw_speaker_map.items():
if isinstance(value, str):
speaker_map[label] = {'name': value.strip(), 'isMe': False}
elif isinstance(value, dict):
speaker_map[label] = {
'name': value.get('name', '').strip() if value.get('name') else '',
'isMe': value.get('isMe', False)
}
else:
return jsonify(api_error('invalid_speaker_value_type', label=label)), 400
# Same rename and follow-up steps as the web update_speakers (#412).
from src.services.speaker_assignment import apply_speaker_names
result = apply_speaker_names(recording, current_user, speaker_map, regenerate_summary)
summary_queued = result['summary_queued']
embeddings_updated = result['embeddings_updated']
snippets_created = result['snippets_created']
return jsonify({
'success': True,
'message': translate('server.apiMessage.speakersUpdated'),
'recording': {
'id': recording.id,
'title': recording.title,
'participants': recording.participants,
'status': recording.status
},
'summary_queued': summary_queued,
'embeddings_updated': embeddings_updated,
'snippets_created': snippets_created
})
except Exception as e:
db.session.rollback()
current_app.logger.error(f"Error assigning speakers for recording {recording_id}: {e}", exc_info=True)
return jsonify(api_error('unexpected_error')), 500
@api_v1_bp.route('/recordings/<int:recording_id>/speakers/identify', methods=['POST'])
@require_scope('process')
@login_required
def identify_speakers(recording_id):
"""
Trigger LLM-based auto-identification of speakers from transcript context.
Returns suggestions only - does not modify the recording.
Uses the shared identification service with JSON schema support,
name sanitization, and fallback logic.
"""
from src.services.speaker_identification import identify_speakers_from_transcript
from src.services.llm import LLMNotConfiguredError
try:
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
if not recording.transcription:
return jsonify(api_error('no_transcription_for_identification')), 400
try:
transcription_data = json.loads(recording.transcription)
except (json.JSONDecodeError, TypeError):
return jsonify(api_error('transcription_format_unsupported_for_identification')), 400
if not isinstance(transcription_data, list):
return jsonify(api_error('transcription_format_unsupported_for_identification')), 400
speaker_map = identify_speakers_from_transcript(transcription_data, current_user.id)
if not speaker_map:
return jsonify(api_error('no_speakers_in_transcription')), 400
return jsonify({'success': True, 'speaker_map': speaker_map})
except LLMNotConfiguredError:
return jsonify(api_error('text_model_not_configured')), 503
except ValueError as ve:
return jsonify({'error': str(ve)}), 503
except Exception as e:
current_app.logger.error(f"Error during auto speaker identification for recording {recording_id}: {e}", exc_info=True)
return jsonify(api_error('unexpected_error')), 500
# =============================================================================
# Processing Operations
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/transcribe', methods=['POST'])
@require_scope('process')
@login_required
def start_transcription(recording_id):
"""Queue transcription for a recording."""
from src.services.job_queue import job_queue
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
# Same checks, clearing and settings as the web reprocess (#412).
from src.services.reprocessing import queue_transcription_reprocess, ReprocessError
data = request.get_json() or {}
overrides = {
'min_speakers': data.get('min_speakers'),
'max_speakers': data.get('max_speakers'),
'hotwords': data.get('hotwords'),
'initial_prompt': data.get('initial_prompt'),
'transcription_model': data.get('transcription_model'),
}
if 'language' in data:
overrides['language'] = data.get('language')
try:
job_id = queue_transcription_reprocess(recording, current_user, overrides)
except ReprocessError as e:
return jsonify(api_error(e.code)), e.status
return jsonify({
'success': True,
'job_id': job_id,
'status': 'QUEUED',
'message': translate('server.apiMessage.transcriptionQueued')
})
@api_v1_bp.route('/recordings/<int:recording_id>/summarize', methods=['POST'])
@require_scope('process')
@login_required
def start_summarization(recording_id):
"""Queue summarization for a recording with optional custom prompt."""
from src.services.job_queue import job_queue
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user, require_edit=True):
return jsonify(api_error('permission_denied')), 403
# Same checks, clearing and parameters as the web reprocess, including
# prompt_mode and prompt_variables (#412).
from src.services.reprocessing import queue_summary_reprocess, ReprocessError
data = request.get_json() or {}
try:
job_id = queue_summary_reprocess(recording, current_user,
custom_prompt=data.get('custom_prompt'),
prompt_mode=data.get('prompt_mode'),
prompt_variables=data.get('prompt_variables'))
except ReprocessError as e:
return jsonify(api_error(e.code)), e.status
return jsonify({
'success': True,
'job_id': job_id,
'status': 'QUEUED',
'message': translate('server.apiMessage.summarizationQueued')
})
# =============================================================================
# Chat with Recording
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/chat', methods=['POST'])
@require_scope('process')
@login_required
def chat_with_recording(recording_id):
"""Chat about a recording's content. with_sources: true returns numbered
sources with segment, time, speaker and a checked quote (mailr spec G9)."""
from src.services.llm import chat_client, call_chat_completion
from src.services.recording_chat import build_chat_messages, parse_sources
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
if not recording.transcription:
return jsonify(api_error('no_transcription')), 400
data = request.get_json()
if not data or not data.get('message'):
return jsonify(api_error('message_required')), 400
with_sources = data.get('with_sources', False)
if not isinstance(with_sources, bool):
return jsonify({'error': translate('server.apiError.invalid_with_sources'), 'code': 'invalid_parameter'}), 400
# Check if chat client is available
if chat_client is None:
return jsonify(api_error('chat_unavailable')), 503
messages, segments = build_chat_messages(recording, current_user, data['message'],
data.get('conversation_history', []), with_sources=with_sources)
try:
from src.services.llm_settings import get_temperature
completion = call_chat_completion(messages, temperature=get_temperature('chat'), user_id=current_user.id)
reply = completion.choices[0].message.content
except Exception as e:
current_app.logger.error(f"Chat error: {e}")
return jsonify(api_error('chat_failed')), 500
sources = []
if with_sources and segments:
reply, sources = parse_sources(reply, segments)
return jsonify({'response': reply, 'sources': sources})
@api_v1_bp.route('/inquire', methods=['POST'])
@require_scope('process')
@login_required
def inquire_v1():
"""Ask a question across recordings (mailr spec G9).
Body: question, filters {recording_ids, tag_ids, folder_ids, speakers,
date_from, date_to}, scope (own|shared|all), mode (rag|agent|auto), stream, history.
"""
import re as _re
from flask import Response, stream_with_context
from src.api.inquire import inquire_stream
from src.services.inquire_agent import agent_enabled
from src.services.recording_scope import scope_condition
if os.environ.get('ENABLE_INQUIRE_MODE', 'false').lower() != 'true':
return jsonify({'error': translate('server.apiError.inquire_off'), 'code': 'feature_disabled'}), 403
body = request.get_json(silent=True) or {}
question = (body.get('question') or '').strip()
if not question:
return jsonify({'error': translate('server.apiError.question_required'), 'code': 'invalid_parameter'}), 400
mode = body.get('mode', 'auto')
if mode not in ('rag', 'agent', 'auto'):
return jsonify({'error': translate('server.apiError.invalid_inquire_mode'), 'code': 'invalid_parameter'}), 400
if mode == 'agent' and not agent_enabled():
return jsonify({'error': translate('server.apiError.inquire_agent_off'), 'code': 'feature_disabled'}), 403
scope = body.get('scope', 'own')
if scope not in ('own', 'shared', 'all'):
return jsonify({'error': translate('server.apiError.invalid_scope'), 'code': 'invalid_parameter'}), 400
filters = body.get('filters') or {}
if not isinstance(filters, dict):
return jsonify({'error': translate('server.apiError.invalid_filters'), 'code': 'invalid_parameter'}), 400
allowed = [rid for (rid,) in db.session.query(Recording.id).filter(scope_condition(current_user.id, scope))]
if filters.get('recording_ids'):
wanted = {int(r) for r in filters['recording_ids'] if str(r).isdigit()}
allowed = [rid for rid in allowed if rid in wanted]
if not allowed:
return jsonify({'answer': 'There are no recordings to search with these filters.', 'citations': [],
'mode_used': 'rag', 'steps': 0, 'usage': None})
data = {
'message': question,
'message_history': body.get('history') or [],
'filter_recording_ids': allowed,
'filter_tags': filters.get('tag_ids') or [],
'filter_folders': filters.get('folder_ids') or [],
'filter_speakers': filters.get('speakers') or [],
'filter_date_from': filters.get('date_from'),
'filter_date_to': filters.get('date_to'),
}
mode_used = 'agent' if (mode != 'rag' and agent_enabled()) else 'rag'
stream = inquire_stream(current_user, data, mode=mode)
if body.get('stream'):
return Response(stream_with_context(stream), mimetype='text/event-stream')
answer, steps, error = [], 0, None
for chunk in stream:
for line in str(chunk).splitlines():
if not line.startswith('data: '):
continue
try:
event = json.loads(line[6:])
except ValueError:
continue
if isinstance(event.get('delta'), str):
answer.append(event['delta'])
if 'error' in event:
error = event['error']
summary = event.get('agent_summary')
if isinstance(summary, dict) and isinstance(summary.get('steps'), int):
steps = summary['steps']
text = ''.join(answer)
if error and not text:
return jsonify({'error': error, 'code': 'inquire_failed'}), 502
# [Title @ 12:34](/recordings/412?t=754) -> [1], for recordings the caller can read.
readable = set(allowed)
citations, numbers = [], {}
link = _re.compile(r'\[([^\]]+)\]\(/recordings/(\d+)(?:\?t=(\d+(?:\.\d+)?))?\)')
def _cite(match):
rid = int(match.group(2))
if rid not in readable:
return match.group(1)
t = float(match.group(3)) if match.group(3) else None
key = (rid, t)
if key not in numbers:
rec = db.session.get(Recording, rid)
numbers[key] = len(citations) + 1
citations.append({'n': numbers[key], 'recording_id': rid, 'title': rec.title if rec else None,
'start_time': t, 'quote': None,
'url': f'/recordings/{rid}' + (f'?t={match.group(3)}' if match.group(3) else '')})
return f'[{numbers[key]}]'
text = link.sub(_cite, text)
return jsonify({'answer': text, 'citations': citations, 'mode_used': mode_used, 'steps': steps, 'usage': None})
# =============================================================================
# Calendar Events
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/events', methods=['GET'])
@require_scope('read')
@login_required
@_conditional('e')
def get_recording_events(recording_id):
"""Get calendar events extracted from a recording."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
events = Event.query.filter_by(recording_id=recording_id).all()
return jsonify({'events': [e.api_dict() for e in events]})
@api_v1_bp.route('/recordings/<int:recording_id>/events/ics', methods=['GET'])
@require_scope('read')
@login_required
def download_events_ics(recording_id):
"""Download all events as ICS file."""
from src.api.events import generate_ics_content
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
events = Event.query.filter_by(recording_id=recording_id).all()
if not events:
return jsonify(api_error('no_events')), 404
# Same builder as the web download (#412).
from src.services.calendar import generate_combined_ics
ics_text = generate_combined_ics(events)
from flask import Response
return Response(
ics_text,
mimetype='text/calendar',
headers={'Content-Disposition': f'attachment; filename=events-{recording_id}.ics'}
)
# =============================================================================
# Audio Download
# =============================================================================
@api_v1_bp.route('/recordings/<int:recording_id>/audio', methods=['GET'])
@require_scope('read')
@login_required
def download_audio(recording_id):
"""Download or stream audio file."""
recording = db.session.get(Recording, recording_id)
if not recording:
return jsonify(api_error('recording_not_found')), 404
if not has_recording_access(recording, current_user):
return jsonify(api_error('permission_denied')), 403
if recording.audio_deleted_at:
return jsonify(api_error('audio_deleted')), 404
if not recording.audio_path:
return jsonify(api_error('no_audio_file')), 404
download = request.args.get('download', 'false').lower() == 'true'
# original_filename is user-controlled at upload time. Sanitize it
# via secure_filename before using it as a download name so null bytes or
# path-traversal segments can't reach a confused download dialog (this also
# feeds the S3 presigned Content-Disposition below).
from werkzeug.utils import secure_filename
raw_name = recording.original_filename or f'recording-{recording_id}.mp3'
safe_download_name = secure_filename(raw_name) or f'recording-{recording_id}'
storage = get_storage_service()
delivery = storage.get_audio_delivery(
recording.audio_path,
download=download,
mime_type=served_media_mime(recording.mime_type or 'audio/mpeg'),
download_name=safe_download_name,
is_public=False,
)
if delivery.mode == 'redirect_url':
return redirect(delivery.url, code=302)
if not delivery.local_path or not os.path.exists(delivery.local_path):
return jsonify(api_error('audio_file_not_found')), 404
return sandbox_media_response(send_file(
delivery.local_path,
mimetype=served_media_mime(recording.mime_type or 'audio/mpeg'),
as_attachment=download,
download_name=safe_download_name,
))
# =============================================================================
# Batch Operations
# =============================================================================
@api_v1_bp.route('/recordings/batch', methods=['PATCH'])
@require_scope('write')
@login_required
def batch_update_recordings():
"""Batch update multiple recordings."""
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
recording_ids = data.get('recording_ids', [])
updates = data.get('updates', {})
if not recording_ids:
return jsonify(api_error('recording_ids_required')), 400
# If folder_id is being set on the batch, validate target folder access
# once up front. The same destination folder applies to every recording
# in the batch, so the permission check is identical for all of them.
target_folder_id = None
if 'folder_id' in updates:
new_folder_id = updates['folder_id']
if new_folder_id is not None:
from src.models.organization import Folder, GroupMembership
target = db.session.get(Folder, new_folder_id)
if not target:
return jsonify(api_error('folder_id_not_found', folderId=new_folder_id)), 404
if target.group_id is None:
if target.user_id != current_user.id:
return jsonify(api_error('target_folder_access_denied')), 403
else:
membership = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=target.group_id
).first()
if not membership:
return jsonify(api_error('target_folder_access_denied')), 403
target_folder_id = new_folder_id
batch_archived = None
if 'is_archived' in updates:
batch_archived = parse_archived_flag(updates['is_archived'])
if batch_archived is None:
return jsonify(api_error('invalid_is_archived')), 400
results = []
for recording_id in recording_ids:
recording = db.session.get(Recording, recording_id)
if not recording:
results.append({'id': recording_id, 'success': False, **api_error('not_found')})
continue
if not has_recording_access(recording, current_user, require_edit=True):
results.append({'id': recording_id, 'success': False, **api_error('permission_denied')})
continue
try:
if 'is_inbox' in updates:
recording.is_inbox = bool(updates['is_inbox'])
if 'is_highlighted' in updates:
recording.is_highlighted = bool(updates['is_highlighted'])
if 'is_archived' in updates:
set_user_archived(recording, current_user, batch_archived, commit=False)
if 'folder_id' in updates:
# `target_folder_id` already validated above (None to remove,
# or a valid folder id the caller has access to).
recording.folder_id = target_folder_id
# Handle tag additions.
# Authorize each tag_id: personal tags must be owned, group
# tags require caller membership in the tag's group. Without
# this check, the batch endpoint was an IDOR that let any
# user attach arbitrary tag_ids (including admin-curated or
# other users' private tags) to their own recordings.
if 'add_tag_ids' in updates:
from src.models.organization import Tag, GroupMembership
for tag_id in updates['add_tag_ids']:
tag = db.session.get(Tag, tag_id)
if tag is None:
continue # silently skip unknown ids
if tag.group_id is None:
if tag.user_id != current_user.id:
continue # not yours
else:
is_member = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=tag.group_id
).first() is not None
if not is_member:
continue # not a member of the tag's group
existing = RecordingTag.query.filter_by(
recording_id=recording_id,
tag_id=tag_id
).first()
if not existing:
max_order = db.session.query(func.max(RecordingTag.order)).filter_by(
recording_id=recording_id
).scalar() or 0
recording_tag = RecordingTag(
recording_id=recording_id,
tag_id=tag_id,
order=max_order + 1
)
db.session.add(recording_tag)
# Handle tag removals. Removing an unauthorised tag from
# one's own recording isn't an IDOR per se (you're only
# editing your own RecordingTag rows) but symmetry keeps
# the contract simple.
if 'remove_tag_ids' in updates:
from src.models.organization import Tag, GroupMembership
for tag_id in updates['remove_tag_ids']:
tag = db.session.get(Tag, tag_id)
if tag is None:
continue
if tag.group_id is None:
if tag.user_id != current_user.id:
continue
else:
is_member = GroupMembership.query.filter_by(
user_id=current_user.id, group_id=tag.group_id
).first() is not None
if not is_member:
continue
RecordingTag.query.filter_by(
recording_id=recording_id,
tag_id=tag_id
).delete()
results.append({'id': recording_id, 'success': True})
except Exception as e:
results.append({'id': recording_id, 'success': False, 'error': str(e)})
db.session.commit()
success_count = sum(1 for r in results if r['success'])
return jsonify({
'success': True,
'updated': success_count,
'failed': len(results) - success_count,
'results': results
})
@api_v1_bp.route('/recordings/batch', methods=['DELETE'])
@require_scope('delete')
@login_required
def batch_delete_recordings():
"""Batch delete multiple recordings."""
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
recording_ids = data.get('recording_ids', [])
if not recording_ids:
return jsonify(api_error('recording_ids_required')), 400
USERS_CAN_DELETE = os.environ.get('USERS_CAN_DELETE', 'true').lower() == 'true'
if not USERS_CAN_DELETE and not current_user.is_admin:
return jsonify(api_error('deletion_not_allowed')), 403
results = []
for recording_id in recording_ids:
recording = db.session.get(Recording, recording_id)
if not recording:
results.append({'id': recording_id, 'success': False, **api_error('not_found')})
continue
if recording.user_id != current_user.id and not current_user.is_admin:
results.append({'id': recording_id, 'success': False, **api_error('permission_denied')})
continue
try:
from src.services.recording_deletion import delete_recording_completely
delete_recording_completely(recording)
results.append({'id': recording_id, 'success': True})
except Exception as e:
db.session.rollback()
current_app.logger.error(f"Error deleting recording {recording_id}: {e}")
results.append({'id': recording_id, 'success': False, **api_error('delete_failed')})
if any(r['success'] for r in results):
from src.services.recording_deletion import cleanup_orphaned_speakers_quietly
cleanup_orphaned_speakers_quietly()
success_count = sum(1 for r in results if r['success'])
return jsonify({
'success': True,
'deleted': success_count,
'failed': len(results) - success_count,
'results': results
})
@api_v1_bp.route('/recordings/batch/transcribe', methods=['POST'])
@require_scope('process')
@login_required
def batch_transcribe_recordings():
"""Batch queue transcriptions for multiple recordings."""
from src.services.job_queue import job_queue
data = request.get_json()
if not data:
return jsonify(api_error('no_data_provided')), 400
recording_ids = data.get('recording_ids', [])
if not recording_ids:
return jsonify(api_error('recording_ids_required')), 400
results = []
for recording_id in recording_ids:
recording = db.session.get(Recording, recording_id)
if not recording:
results.append({'id': recording_id, 'success': False, **api_error('not_found')})
continue
if not has_recording_access(recording, current_user, require_edit=True):
results.append({'id': recording_id, 'success': False, **api_error('permission_denied')})
continue
# Same checks, clearing and settings as a single reprocess (#412).
from src.services.reprocessing import queue_transcription_reprocess, ReprocessError
try:
job_id = queue_transcription_reprocess(recording, current_user)
results.append({'id': recording_id, 'success': True, 'job_id': job_id})
except ReprocessError as e:
results.append({'id': recording_id, 'success': False, 'error': e.message})
except Exception as e:
results.append({'id': recording_id, 'success': False, 'error': str(e)})
success_count = sum(1 for r in results if r['success'])
return jsonify({
'success': True,
'queued': success_count,
'failed': len(results) - success_count,
'results': results
})
# =============================================================================
# Settings
# =============================================================================
@api_v1_bp.route('/settings/auto-summarization', methods=['PUT'])
@require_scope('account')
@login_required
def update_auto_summarization():
"""Toggle auto-summarization for the current user."""
data = request.get_json()
if data is None:
return jsonify(api_error('invalid_json')), 400
if 'enabled' not in data:
return jsonify(api_error('enabled_field_required')), 400
current_user.auto_summarization = bool(data['enabled'])
db.session.commit()
return jsonify({
'success': True,
'auto_summarization': current_user.auto_summarization
})
def _normalize_asr_filename(file_name, uploaded_file):
raw_name = (file_name or uploaded_file.filename or '').strip()
raw_name = re.split(r'[/\\]+', raw_name)[-1]
normalized = secure_filename(raw_name)
if not normalized:
normalized = secure_filename(uploaded_file.filename or '') or 'recording.bin'
stem, extension = os.path.splitext(normalized)
extension = extension[:20]
max_stem = max(1, 180 - len(extension))
return f'{stem[:max_stem]}{extension}'
def _asr_meeting_date(raw_date):
if raw_date is None or str(raw_date).strip() == '':
return None
try:
timestamp = float(raw_date)
if not math.isfinite(timestamp) or timestamp < 0:
return None
# ASR documents only "epoch time". Accept both common units.
if timestamp > 100_000_000_000:
timestamp /= 1000
parsed = datetime.fromtimestamp(timestamp, tz=timezone.utc)
return parsed.isoformat().replace('+00:00', 'Z')
except (ValueError, TypeError, OSError, OverflowError):
return None
_ASR_RATE_UNITS_PER_MINUTE = 520
_ASR_MIN_REQUEST_COST = 52
def _asr_upload_rate_cost():
"""Bound both requests and declared MiB with one pre-parse IP bucket."""
content_length = request.content_length
if content_length is None:
return _ASR_RATE_UNITS_PER_MINUTE
declared_mib = max(1, math.ceil(content_length / (1024 * 1024)))
return max(_ASR_MIN_REQUEST_COST, declared_mib)
@api_v1_bp.route('/integrations/asr-voice-recorder/upload', methods=['POST'])
@require_scope('upload')
@rate_limit(f'{_ASR_RATE_UNITS_PER_MINUTE} per minute', cost=_asr_upload_rate_cost)
def upload_from_asr_voice_recorder():
"""Accept an ASR Voice Recorder connection test or completed upload."""
try:
# ASR sends its token inside the multipart body, so Flask must parse
# the request before authentication can complete. Apply the regular
# audio-file ceiling to this route before parsing instead of the
# larger global video ceiling. The small allowance covers multipart
# headers and metadata around a file at the configured limit.
from src.models import SystemSetting
regular_limit_mb = max(1, int(SystemSetting.get_setting('max_file_size_mb', 250)))
# Assigning request.max_content_length requires Flask >= 3.1 /
# Werkzeug >= 3.1 (older versions expose it as a read-only property
# and this line raises AttributeError, 500ing every upload).
# requirements.txt pins flask==3.1.0 / werkzeug==3.1.3.
request.max_content_length = regular_limit_mb * 1024 * 1024 + 64 * 1024
secret = request.form.get('secret', '')
owner = load_user_from_token_value(secret)
if owner is None:
return jsonify(api_error('authentication_failed')), 401
# A scoped token must carry 'upload' (mailr spec G1); full tokens pass.
_token = request.environ.get('_speakr_secret_token')
if _token is not None and _token.scope_set is not None and 'upload' not in _token.scope_set:
return jsonify(api_error('authentication_failed')), 401
uploaded_file = request.files.get('file')
if uploaded_file is None:
upload_fields = ('file_name', 'date', 'duration', 'note')
has_upload_metadata = any(request.form.get(field) for field in upload_fields)
if not has_upload_metadata:
return jsonify({'status': 'ok', 'connection_test': True}), 200
return jsonify(api_error('no_file_provided')), 400
form = {}
note = request.form.get('note')
if note is not None:
form['notes'] = note
meeting_date = _asr_meeting_date(request.form.get('date'))
if meeting_date:
form['meeting_date'] = meeting_date
return ingest_uploaded_recording(
owner=owner,
uploaded_file=uploaded_file,
form=form,
original_filename=_normalize_asr_filename(
request.form.get('file_name'),
uploaded_file,
),
processing_source='asr_voice_recorder',
success_status=200,
reuse_duplicate=True,
)
except RequestEntityTooLarge:
return jsonify(api_error('file_too_large')), 413
@api_v1_bp.route('/recordings/upload', methods=['POST'])
@require_scope('upload')
@login_required
def upload_recording():
"""
Upload a recording and queue transcription (API).
Multipart form-data fields:
- file (required)
- notes (optional)
- title (optional)
- meeting_date (optional, ISO 8601)
- file_last_modified (optional, ms epoch)
- language (optional)
- min_speakers (optional)
- max_speakers (optional)
- hotwords (optional)
- initial_prompt (optional)
- transcription_model (optional, validated against admin-curated list)
- prompt_variables (optional, JSON object of `{variable_name: value}`
substituted into `{{name}}` placeholders in the resolved summary
prompt at summarisation time)
- folder_id (optional)
- tag_ids[0], tag_ids[1], ... (optional)
- tag_id (optional, legacy)
- participants (optional, comma-separated, at most 500 characters)
- external_refs (optional, JSON array of references)
- idempotency_key (optional, 1 to 100 characters)
- strict (optional, true: a tag or folder you cannot use is an error)
"""
from src.api.recordings import ingest_uploaded_recording
from src.models import Folder, GroupMembership, Tag
from src.services import external_refs as xr
form = request.form
participants = form.get('participants')
if participants is not None and len(participants) > 500:
return jsonify({'error': translate('server.apiError.participants_too_long'), 'code': 'invalid_parameter'}), 400
clean_refs = []
if form.get('external_refs'):
try:
clean_refs = xr.validate_list(json.loads(form['external_refs']))
except ValueError as e:
code = getattr(e, 'code', 'invalid_parameter')
status = getattr(e, 'status', 400)
return jsonify({'error': str(e) if isinstance(e, xr.RefError) else 'external_refs must be JSON',
'code': code}), status
key = (form.get('idempotency_key') or '').strip() or None
if key is not None and len(key) > 100:
return jsonify({'error': translate('server.apiError.invalid_idempotency_key'), 'code': 'invalid_parameter'}), 400
cutoff = datetime.utcnow() - timedelta(hours=24)
def _replay():
earlier = (Recording.query
.filter(Recording.user_id == current_user.id, Recording.upload_idempotency_key == key,
Recording.created_at >= cutoff)
.order_by(Recording.id.desc()).first())
if earlier is None:
return None
data = earlier.to_dict(viewer_user=current_user)
data['external_refs'] = [r.to_dict() for r in xr.refs_for(earlier.id, current_user.id)]
data['idempotent_replay'] = True
return jsonify(data), 200
if key:
replay = _replay()
if replay is not None:
return replay
# The key is unique per user (#476): one older than 24 hours is
# cleared so this upload can take it.
Recording.query.filter(Recording.user_id == current_user.id, Recording.upload_idempotency_key == key,
Recording.created_at < cutoff).update({'upload_idempotency_key': None},
synchronize_session=False)
db.session.commit()
# Report tags and folders the upload cannot use (the pipeline drops them).
def _usable(item):
return item is not None and (item.user_id == current_user.id or (
item.group_id and GroupMembership.query.filter_by(group_id=item.group_id,
user_id=current_user.id).first()))
asked_tags = [form.get(f'tag_ids[{i}]') for i in range(100) if form.get(f'tag_ids[{i}]')] \
or ([form.get('tag_id')] if form.get('tag_id') else [])
ignored_tags = []
for raw in asked_tags:
tag = db.session.get(Tag, int(raw)) if str(raw).isdigit() else None
if not _usable(tag):
ignored_tags.append(int(raw) if str(raw).isdigit() else raw)
ignored_folder = None
if form.get('folder_id'):
raw = form.get('folder_id')
folder = db.session.get(Folder, int(raw)) if str(raw).isdigit() else None
if not _usable(folder):
ignored_folder = int(raw) if str(raw).isdigit() else raw
if (form.get('strict') or '').lower() == 'true' and (ignored_tags or ignored_folder is not None):
return jsonify({'error': translate('server.apiError.upload_tag_or_folder_forbidden'),
'code': 'invalid_parameter',
'ignored': {'tag_ids': ignored_tags, 'folder_id': ignored_folder}}), 400
def _prepare(recording):
if participants is not None:
recording.participants = participants.strip() or None
if key:
recording.upload_idempotency_key = key
db.session.flush()
for clean in clean_refs:
xr.add(recording, current_user.id, clean)
response = ingest_uploaded_recording(owner=current_user, uploaded_file=request.files.get('file'),
form=form, prepare=_prepare, on_conflict=_replay if key else None)
body, status = (response if isinstance(response, tuple) else (response, response.status_code))
if status in (200, 201, 202):
data = body.get_json() or {}
if data.get('id'):
data['external_refs'] = [r.to_dict() for r in xr.refs_for(data['id'], current_user.id)]
data['ignored'] = {'tag_ids': ignored_tags, 'folder_id': ignored_folder}
return jsonify(data), status
return response