Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Add comprehensive API v1 documentation and Swagger UI

Murtaza Nasirebb4f34474ca
diff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.md
new file mode 100644
index 00000000..642ceb91
--- /dev/null
+++ b/docs/user-guide/api-reference.md
@@ -0,0 +1,871 @@
+# API Reference
+
+Speakr provides a comprehensive REST API (v1) for automation tools, dashboard widgets, and custom integrations. This reference documents all available endpoints.
+
+!!! tip "Interactive Documentation"
+ Access the interactive Swagger UI documentation at `/api/v1/docs` on your Speakr instance. You can test endpoints directly from your browser.
+
+## Base URL
+
+All API v1 endpoints are prefixed with `/api/v1`:
+
+```
+https://your-speakr-instance.com/api/v1/
+```
+
+## Authentication
+
+All endpoints require authentication. See [API Tokens](api-tokens.md) for details on creating and managing tokens.
+
+=== "Bearer Token (Recommended)"
+ ```bash
+ curl -H "Authorization: Bearer YOUR_TOKEN" \
+ https://speakr.example.com/api/v1/stats
+ ```
+
+=== "X-API-Token Header"
+ ```bash
+ curl -H "X-API-Token: YOUR_TOKEN" \
+ https://speakr.example.com/api/v1/stats
+ ```
+
+=== "Query Parameter"
+ ```bash
+ curl "https://speakr.example.com/api/v1/stats?token=YOUR_TOKEN"
+ ```
+
+## OpenAPI Specification
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/v1/docs` | Interactive Swagger UI |
+| `GET /api/v1/openapi.json` | OpenAPI 3.0 specification |
+
+---
+
+## Stats
+
+Dashboard-compatible statistics endpoint, designed for integration with homepage widgets like [gethomepage.dev](https://gethomepage.dev/).
+
+### Get Statistics
+
+```http
+GET /api/v1/stats
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `scope` | string | `user` | `user` for personal stats, `all` for global (admin only) |
+
+**Response:**
+
+```json
+{
+ "recordings": {
+ "total": 150,
+ "completed": 120,
+ "processing": 5,
+ "pending": 20,
+ "failed": 5
+ },
+ "storage": {
+ "used_bytes": 5368709120,
+ "used_human": "5.0 GB"
+ },
+ "queue": {
+ "jobs_queued": 3,
+ "jobs_processing": 1
+ },
+ "tokens": {
+ "used_this_month": 450000,
+ "budget": 1000000,
+ "percentage": 45.0
+ },
+ "activity": {
+ "recordings_today": 3,
+ "last_transcription": "2024-01-15T14:30:00Z"
+ }
+}
+```
+
+??? example "gethomepage.dev Widget Configuration"
+ ```yaml
+ - Speakr:
+ widget:
+ type: customapi
+ url: https://speakr.example.com/api/v1/stats
+ headers:
+ Authorization: Bearer YOUR_TOKEN
+ mappings:
+ - field: recordings.completed
+ label: Completed
+ - field: storage.used_human
+ label: Storage
+ - field: tokens.percentage
+ label: Token Usage
+ format: percent
+ - field: activity.recordings_today
+ label: Today
+ ```
+
+---
+
+## Recordings
+
+### List Recordings
+
+```http
+GET /api/v1/recordings
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `page` | integer | 1 | Page number |
+| `per_page` | integer | 25 | Items per page (max: 100) |
+| `status` | string | `all` | Filter: `all`, `pending`, `processing`, `completed`, `failed` |
+| `sort_by` | string | `created_at` | Sort field: `created_at`, `meeting_date`, `title`, `file_size` |
+| `sort_order` | string | `desc` | Sort order: `asc`, `desc` |
+| `date_from` | string | - | Filter from date (ISO format) |
+| `date_to` | string | - | Filter to date (ISO format) |
+| `tag_id` | integer | - | Filter by tag ID |
+| `q` | string | - | Search query (title, participants) |
+| `inbox` | boolean | - | Filter by inbox status |
+| `starred` | boolean | - | Filter by starred status |
+
+**Response:**
+
+```json
+{
+ "recordings": [
+ {
+ "id": 123,
+ "title": "Team Meeting",
+ "status": "COMPLETED",
+ "created_at": "2024-01-15T10:00:00Z",
+ "meeting_date": "2024-01-15T09:00:00Z",
+ "file_size": 15728640,
+ "original_filename": "meeting.mp3",
+ "participants": "Alice, Bob",
+ "is_inbox": false,
+ "is_highlighted": true,
+ "audio_available": true,
+ "has_transcription": true,
+ "has_summary": true,
+ "tags": [
+ {"id": 1, "name": "Work", "color": "#3B82F6"}
+ ]
+ }
+ ],
+ "pagination": {
+ "page": 1,
+ "per_page": 25,
+ "total": 150,
+ "total_pages": 6,
+ "has_next": true,
+ "has_prev": false
+ }
+}
+```
+
+### Get Recording Details
+
+```http
+GET /api/v1/recordings/{id}
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `format` | string | `full` | `full` or `minimal` (excludes large text fields) |
+| `include` | string | `transcription,summary,notes` | Comma-separated fields to include |
+
+**Response:**
+
+```json
+{
+ "id": 123,
+ "title": "Team Meeting",
+ "status": "COMPLETED",
+ "participants": "Alice, Bob",
+ "created_at": "2024-01-15T10:00:00Z",
+ "meeting_date": "2024-01-15T09:00:00Z",
+ "completed_at": "2024-01-15T10:05:00Z",
+ "file_size": 15728640,
+ "original_filename": "meeting.mp3",
+ "mime_type": "audio/mpeg",
+ "is_inbox": false,
+ "is_highlighted": true,
+ "audio_available": true,
+ "processing_time_seconds": 45.2,
+ "transcription": "Alice: Hello everyone...",
+ "summary": "## Meeting Summary\n- Key point 1...",
+ "notes": "Personal notes...",
+ "tags": [{"id": 1, "name": "Work", "color": "#3B82F6"}]
+}
+```
+
+!!! note "Transcript Formatting"
+ The `transcription` field is automatically formatted using your default transcript template. Configure templates in Account Settings → Transcript Templates.
+
+### Get Transcript
+
+```http
+GET /api/v1/recordings/{id}/transcript
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `format` | string | `json` | Output format: `json`, `text`, `srt`, `vtt` |
+
+=== "JSON Format"
+ ```json
+ {
+ "format": "json",
+ "segments": [
+ {
+ "speaker": "Alice",
+ "sentence": "Hello everyone",
+ "start_time": 0.0,
+ "end_time": 2.5
+ }
+ ]
+ }
+ ```
+
+=== "Text Format"
+ Uses your default transcript template:
+ ```json
+ {
+ "format": "text",
+ "content": "Alice: Hello everyone\n\nBob: Hi Alice..."
+ }
+ ```
+
+=== "SRT Format"
+ ```json
+ {
+ "format": "srt",
+ "content": "1\n00:00:00,000 --> 00:00:02,500\nHello everyone\n\n2\n..."
+ }
+ ```
+
+=== "VTT Format"
+ ```json
+ {
+ "format": "vtt",
+ "content": "WEBVTT\n\n00:00:00.000 --> 00:00:02.500\n<v Alice>Hello everyone\n\n..."
+ }
+ ```
+
+### Get Summary
+
+```http
+GET /api/v1/recordings/{id}/summary
+```
+
+**Response:**
+
+```json
+{
+ "summary": "## Meeting Summary\n\n### Key Points\n- Point 1...",
+ "has_summary": true
+}
+```
+
+### Get Notes
+
+```http
+GET /api/v1/recordings/{id}/notes
+```
+
+**Response:**
+
+```json
+{
+ "notes": "My personal notes about this meeting...",
+ "has_notes": true
+}
+```
+
+### Get Processing Status
+
+```http
+GET /api/v1/recordings/{id}/status
+```
+
+**Response:**
+
+```json
+{
+ "id": 123,
+ "status": "PROCESSING",
+ "queue_position": 2,
+ "error_message": null,
+ "completed_at": null
+}
+```
+
+**Status Values:**
+
+| Status | Description |
+|--------|-------------|
+| `PENDING` | Waiting in queue |
+| `PROCESSING` | Transcription in progress |
+| `SUMMARIZING` | Summary generation in progress |
+| `COMPLETED` | Processing finished successfully |
+| `FAILED` | Processing failed (check `error_message`) |
+
+### Update Recording
+
+```http
+PATCH /api/v1/recordings/{id}
+```
+
+**Request Body:**
+
+```json
+{
+ "title": "Updated Title",
+ "participants": "Alice, Bob, Charlie",
+ "notes": "Updated notes...",
+ "summary": "Updated summary...",
+ "meeting_date": "2024-01-15T09:00:00Z",
+ "is_inbox": false,
+ "is_highlighted": true
+}
+```
+
+All fields are optional.
+
+### Replace Notes
+
+```http
+PUT /api/v1/recordings/{id}/notes
+```
+
+**Request Body:**
+
+```json
+{
+ "notes": "New notes content..."
+}
+```
+
+### Replace Summary
+
+```http
+PUT /api/v1/recordings/{id}/summary
+```
+
+**Request Body:**
+
+```json
+{
+ "summary": "## New Summary\n- Point 1..."
+}
+```
+
+### Delete Recording
+
+```http
+DELETE /api/v1/recordings/{id}
+```
+
+**Response:**
+
+```json
+{
+ "success": true,
+ "message": "Recording deleted"
+}
+```
+
+---
+
+## Tags
+
+### List Tags
+
+```http
+GET /api/v1/tags
+```
+
+Returns both personal tags and group tags you have access to.
+
+**Response:**
+
+```json
+{
+ "tags": [
+ {
+ "id": 1,
+ "name": "Work Meetings",
+ "color": "#3B82F6",
+ "is_group_tag": false,
+ "group_id": null,
+ "custom_prompt": "Focus on action items...",
+ "default_language": "en",
+ "default_min_speakers": 2,
+ "default_max_speakers": 10,
+ "protect_from_deletion": false,
+ "can_edit": true
+ }
+ ]
+}
+```
+
+### Create Tag
+
+```http
+POST /api/v1/tags
+```
+
+**Request Body:**
+
+```json
+{
+ "name": "Interviews",
+ "color": "#10B981",
+ "custom_prompt": "Extract candidate qualifications...",
+ "default_language": "en",
+ "default_min_speakers": 2,
+ "default_max_speakers": 3,
+ "group_id": null
+}
+```
+
+### Update Tag
+
+```http
+PUT /api/v1/tags/{id}
+```
+
+**Request Body:**
+
+```json
+{
+ "name": "Updated Name",
+ "color": "#EF4444",
+ "custom_prompt": "New prompt..."
+}
+```
+
+### Delete Tag
+
+```http
+DELETE /api/v1/tags/{id}
+```
+
+### Add Tags to Recording
+
+```http
+POST /api/v1/recordings/{id}/tags
+```
+
+**Request Body:**
+
+```json
+{
+ "tag_ids": [1, 2, 3]
+}
+```
+
+### Remove Tag from Recording
+
+```http
+DELETE /api/v1/recordings/{id}/tags/{tag_id}
+```
+
+---
+
+## Speakers
+
+### List Speakers
+
+```http
+GET /api/v1/speakers
+```
+
+**Response:**
+
+```json
+{
+ "speakers": [
+ {
+ "id": 1,
+ "name": "John Doe",
+ "use_count": 45,
+ "last_used": "2024-01-15T14:30:00Z",
+ "confidence_score": 0.87,
+ "has_voice_profile": true
+ }
+ ]
+}
+```
+
+### Create Speaker
+
+```http
+POST /api/v1/speakers
+```
+
+**Request Body:**
+
+```json
+{
+ "name": "Jane Smith"
+}
+```
+
+### Update Speaker
+
+```http
+PUT /api/v1/speakers/{id}
+```
+
+Updates the speaker name and cascades changes to all recordings.
+
+**Request Body:**
+
+```json
+{
+ "name": "Jane Doe"
+}
+```
+
+### Delete Speaker
+
+```http
+DELETE /api/v1/speakers/{id}
+```
+
+### Get Recording Speakers
+
+```http
+GET /api/v1/recordings/{id}/speakers
+```
+
+Returns speakers in the recording with voice-based identification suggestions.
+
+**Response:**
+
+```json
+{
+ "speakers": [
+ {
+ "label": "SPEAKER_00",
+ "identified_name": "John Doe",
+ "speaker_id": 1,
+ "segment_count": 23
+ }
+ ],
+ "suggestions": {
+ "SPEAKER_01": [
+ {"speaker_id": 2, "name": "Jane Smith", "similarity": 89.5}
+ ]
+ }
+}
+```
+
+---
+
+## Processing Operations
+
+### Queue Transcription
+
+```http
+POST /api/v1/recordings/{id}/transcribe
+```
+
+**Request Body:**
+
+```json
+{
+ "language": "en",
+ "min_speakers": 1,
+ "max_speakers": 5
+}
+```
+
+All parameters are optional.
+
+**Response:**
+
+```json
+{
+ "success": true,
+ "job_id": "abc123",
+ "status": "QUEUED",
+ "message": "Transcription queued"
+}
+```
+
+### Queue Summarization
+
+```http
+POST /api/v1/recordings/{id}/summarize
+```
+
+**Request Body:**
+
+```json
+{
+ "custom_prompt": "Focus on technical decisions and action items only"
+}
+```
+
+The custom prompt overrides the recording's tag prompts and user defaults.
+
+---
+
+## Chat
+
+### Chat with Recording
+
+```http
+POST /api/v1/recordings/{id}/chat
+```
+
+Ask questions about a recording's content using AI.
+
+**Request Body:**
+
+```json
+{
+ "message": "What were the main action items discussed?",
+ "conversation_history": [
+ {"role": "user", "content": "Who attended?"},
+ {"role": "assistant", "content": "John and Jane attended..."}
+ ]
+}
+```
+
+**Response:**
+
+```json
+{
+ "response": "The main action items were:\n1. Complete the report by Friday\n2. Schedule follow-up meeting...",
+ "sources": []
+}
+```
+
+---
+
+## Events
+
+### Get Calendar Events
+
+```http
+GET /api/v1/recordings/{id}/events
+```
+
+Returns calendar events extracted from the recording.
+
+**Response:**
+
+```json
+{
+ "events": [
+ {
+ "id": 1,
+ "title": "Follow-up Meeting",
+ "start_datetime": "2024-01-22T10:00:00Z",
+ "end_datetime": "2024-01-22T11:00:00Z",
+ "description": "Discuss project progress",
+ "location": "Conference Room A"
+ }
+ ]
+}
+```
+
+### Download Events as ICS
+
+```http
+GET /api/v1/recordings/{id}/events/ics
+```
+
+Returns an ICS file containing all events from the recording.
+
+---
+
+## Audio
+
+### Download Audio
+
+```http
+GET /api/v1/recordings/{id}/audio
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `download` | boolean | `false` | `true` to force download, `false` to stream |
+
+---
+
+## Batch Operations
+
+### Batch Update Recordings
+
+```http
+PATCH /api/v1/recordings/batch
+```
+
+**Request Body:**
+
+```json
+{
+ "recording_ids": [1, 2, 3],
+ "updates": {
+ "is_inbox": false,
+ "is_highlighted": true,
+ "add_tag_ids": [5],
+ "remove_tag_ids": [2]
+ }
+}
+```
+
+**Response:**
+
+```json
+{
+ "success": true,
+ "updated": 3,
+ "failed": 0,
+ "results": [
+ {"id": 1, "success": true},
+ {"id": 2, "success": true},
+ {"id": 3, "success": true}
+ ]
+}
+```
+
+### Batch Delete Recordings
+
+```http
+DELETE /api/v1/recordings/batch
+```
+
+**Request Body:**
+
+```json
+{
+ "recording_ids": [1, 2, 3]
+}
+```
+
+### Batch Queue Transcriptions
+
+```http
+POST /api/v1/recordings/batch/transcribe
+```
+
+**Request Body:**
+
+```json
+{
+ "recording_ids": [1, 2, 3]
+}
+```
+
+---
+
+## Error Responses
+
+All endpoints return consistent error responses:
+
+```json
+{
+ "error": "Error message description"
+}
+```
+
+**Common HTTP Status Codes:**
+
+| Code | Description |
+|------|-------------|
+| `200` | Success |
+| `201` | Created |
+| `400` | Bad Request - Invalid parameters |
+| `401` | Unauthorized - Invalid or missing token |
+| `403` | Forbidden - No permission for this resource |
+| `404` | Not Found - Resource doesn't exist |
+| `500` | Internal Server Error |
+
+---
+
+## Rate Limits
+
+API endpoints are rate-limited to prevent abuse:
+
+| Endpoint Type | Limit |
+|---------------|-------|
+| Stats | 60 requests/minute |
+| GET endpoints | 100 requests/minute |
+| PATCH/DELETE | 30 requests/minute |
+| Processing operations | 10 requests/minute |
+| Batch operations | 10 requests/minute |
+
+---
+
+## Integration Examples
+
+### Python SDK Pattern
+
+```python
+import requests
+
+class SpeakrAPI:
+ def __init__(self, base_url, token):
+ self.base_url = base_url.rstrip('/')
+ self.session = requests.Session()
+ self.session.headers['Authorization'] = f'Bearer {token}'
+
+ def get_stats(self):
+ return self.session.get(f'{self.base_url}/api/v1/stats').json()
+
+ def list_recordings(self, status='all', page=1):
+ return self.session.get(
+ f'{self.base_url}/api/v1/recordings',
+ params={'status': status, 'page': page}
+ ).json()
+
+ def get_transcript(self, recording_id, format='text'):
+ return self.session.get(
+ f'{self.base_url}/api/v1/recordings/{recording_id}/transcript',
+ params={'format': format}
+ ).json()
+
+# Usage
+api = SpeakrAPI('https://speakr.example.com', 'YOUR_TOKEN')
+stats = api.get_stats()
+print(f"Total recordings: {stats['recordings']['total']}")
+```
+
+### n8n Workflow
+
+1. Use **HTTP Request** node
+2. Set **Method** to `GET`
+3. Set **URL** to `https://your-instance/api/v1/recordings`
+4. In **Authentication**, select **Header Auth**
+5. Add header: `Authorization` = `Bearer YOUR_TOKEN`
+
+### Zapier Integration
+
+Use the **Webhooks by Zapier** app with:
+
+- **Trigger**: Custom webhook
+- **Action**: GET request to `/api/v1/recordings`
+- **Headers**: `Authorization: Bearer YOUR_TOKEN`
+
+---
+
+Next: Learn about [API Tokens](api-tokens.md) for authentication setup.
diff --git a/docs/user-guide/api-tokens.md b/docs/user-guide/api-tokens.md
index 1f8ac1ca..d27f7b45 100644
--- a/docs/user-guide/api-tokens.md
+++ b/docs/user-guide/api-tokens.md
@@ -37,7 +37,7 @@ The most secure and standard method:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
- https://your-speakr-instance.com/api/recordings
+ https://your-speakr-instance.com/api/v1/recordings
```
### X-API-Token Header
@@ -46,7 +46,7 @@ Alternative header format:
```bash
curl -H "X-API-Token: YOUR_TOKEN_HERE" \
- https://your-speakr-instance.com/api/recordings
+ https://your-speakr-instance.com/api/v1/recordings
```
### API-Token Header
@@ -55,7 +55,7 @@ Another alternative:
```bash
curl -H "API-Token: YOUR_TOKEN_HERE" \
- https://your-speakr-instance.com/api/recordings
+ https://your-speakr-instance.com/api/v1/recordings
```
### Query Parameter
@@ -63,26 +63,35 @@ curl -H "API-Token: YOUR_TOKEN_HERE" \
For simple integrations (less secure - token visible in logs):
```bash
-curl "https://your-speakr-instance.com/api/recordings?token=YOUR_TOKEN_HERE"
+curl "https://your-speakr-instance.com/api/v1/recordings?token=YOUR_TOKEN_HERE"
```
## Available API Endpoints
-Once authenticated, you can access the same data available through the web interface:
+Speakr provides a comprehensive REST API with endpoints for recordings, tags, speakers, processing operations, and more.
+
+!!! tip "Full API Documentation"
+ See the complete [API Reference](api-reference.md) for all endpoints, parameters, and examples. You can also access interactive documentation at `/api/v1/docs` on your instance.
+
+**Quick reference of common endpoints:**
| Endpoint | Method | Description |
|----------|--------|-------------|
-| `/api/recordings` | GET | List your recordings with pagination |
-| `/api/recordings/<id>` | GET | Get a specific recording's details |
-| `/api/recordings/<id>/transcript` | GET | Get the transcript text |
-| `/api/recordings/<id>/summary` | GET | Get the AI-generated summary |
-| `/api/tags` | GET | List your tags |
+| `/api/v1/stats` | GET | Dashboard statistics (gethomepage.dev compatible) |
+| `/api/v1/recordings` | GET | List recordings with filtering and pagination |
+| `/api/v1/recordings/<id>` | GET | Get recording details |
+| `/api/v1/recordings/<id>/transcript` | GET | Get transcript (json, text, srt, vtt) |
+| `/api/v1/recordings/<id>/summary` | GET | Get AI-generated summary |
+| `/api/v1/recordings/<id>/transcribe` | POST | Queue transcription |
+| `/api/v1/recordings/<id>/summarize` | POST | Queue summarization |
+| `/api/v1/tags` | GET | List your tags |
+| `/api/v1/speakers` | GET | List your speakers |
### Example: List Recordings
```bash
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
- "https://your-speakr-instance.com/api/recordings?page=1&per_page=25"
+ "https://your-speakr-instance.com/api/v1/recordings?page=1&per_page=25"
```
Response:
@@ -170,7 +179,7 @@ BASE_URL = "https://your-speakr-instance.com"
headers = {"Authorization": f"Bearer {TOKEN}"}
# List recordings
-response = requests.get(f"{BASE_URL}/api/recordings", headers=headers)
+response = requests.get(f"{BASE_URL}/api/v1/recordings", headers=headers)
recordings = response.json()["recordings"]
for recording in recordings:
@@ -186,7 +195,7 @@ BASE_URL="https://your-speakr-instance.com"
# Get all recordings
curl -s -H "Authorization: Bearer $TOKEN" \
- "$BASE_URL/api/recordings" | jq '.recordings[].title'
+ "$BASE_URL/api/v1/recordings" | jq '.recordings[].title'
```
## Troubleshooting
diff --git a/mkdocs.yml b/mkdocs.yml
index c382c669..5f70a1c9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -166,6 +166,8 @@ nav:
- Inquire Mode: user-guide/inquire-mode.md
- Sharing Recordings: user-guide/sharing.md
- Account Settings: user-guide/settings.md
+ - API Tokens: user-guide/api-tokens.md
+ - API Reference: user-guide/api-reference.md
- Admin Guide:
- admin-guide/index.md
diff --git a/src/api/api_v1.py b/src/api/api_v1.py
index ae952025..c27b8ed2 100644
--- a/src/api/api_v1.py
+++ b/src/api/api_v1.py
@@ -78,7 +78,7 @@ def format_bytes(bytes_value: int) -> str:
OPENAPI_SPEC = {
"openapi": "3.0.3",
"info": {
- "title": "Speakr API v1",
+ "title": "Speakr API",
"description": "REST API for Speakr - Audio transcription and note-taking application.\n\n## Authentication\nAll 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\nGenerate tokens in Settings > API Tokens.",
"version": "1.0.0"
},