Skip to content

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

Python

API v1: external references and upload metadata (mailr spec G8)

Murtaza Nasirb00aabb6268c
diff --git a/docs/admin-guide/webhooks.md b/docs/admin-guide/webhooks.md
index 7c8cccc3..92fe698a 100644
--- a/docs/admin-guide/webhooks.md
+++ b/docs/admin-guide/webhooks.md
@@ -38,6 +38,7 @@ app, through API v1 or by a speaker rename or merge. `fields_changed` uses these
| `transcript` | the transcript text or its speaker names |
| `speakers` | which name each diarization label shows |
| `tags` | a tag was added, removed or reordered |
+| `external_refs` | the webhook owner's external references |
| `events` | extracted calendar events changed |
| `is_inbox`, `is_highlighted`, `is_archived` | the owner's flags |
| `audio` | the audio was removed |
@@ -80,7 +81,8 @@ Every delivery is a `POST` with a JSON body shaped like:
- `timestamp` and `occurred_at` are the time the event happened (UTC, microseconds). They do
not change on retries: the body is stored once and every attempt sends the same bytes.
- `data` of every `recording.*` event carries `updated_at`, the recording's last change as
- in the API (absent for `recording.deleted`).
+ in the API, and `external_refs`, the webhook owner's references (both absent for
+ `recording.deleted`).
- The body is `json.dumps(envelope, separators=(',', ':'), ensure_ascii=False)` in UTF-8.
Verify the signature over the raw bytes you received, never over re-serialised JSON.
diff --git a/docs/user-guide/api-reference.md b/docs/user-guide/api-reference.md
index 11759f1c..10e64ebc 100644
--- a/docs/user-guide/api-reference.md
+++ b/docs/user-guide/api-reference.md
@@ -270,41 +270,61 @@ Upload a recording as multipart form-data and immediately queue transcription.
| Field | Type | Required | Description |
|-------|------|----------|-------------|
-| `file` | file | yes | Audio file to upload |
-| `notes` | string | no | Optional notes |
-| `file_last_modified` | string | no | Client file lastModified (ms epoch) |
+| `file` | file | yes | Audio or video file |
+| `title` | string | no | Title. Without it, the title comes from your title settings once the transcript exists. |
+| `participants` | string | no | Comma-separated names, at most 500 characters |
+| `meeting_date` | string | no | ISO 8601. Takes precedence over every other date source. |
+| `file_last_modified` | string | no | The file's last-modified time in milliseconds since the epoch. Used when `meeting_date` is absent and no date is read from the file name. |
+| `notes` | string | no | Notes |
+| `folder_id` | integer | no | Folder (your own or a group folder you belong to) |
+| `tag_ids[0]`, `tag_ids[1]`, ... | integer | no | Tags, in order (your own or group tags you belong to) |
+| `tag_id` | integer | no | Single tag (legacy) |
+| `external_refs` | string | no | JSON array of [external references](#external-references) without `id` |
+| `idempotency_key` | string | no | 1 to 100 characters; see below |
+| `strict` | boolean | no | `true`: a tag or folder you cannot use is an error (`400`). Default `false`: it is dropped and reported in `ignored`. |
| `language` | string | no | Language hint (ISO 639-1) |
-| `min_speakers` | integer | no | Min speaker count |
-| `max_speakers` | integer | no | Max speaker count |
-| `tag_ids[0]`, `tag_ids[1]`, ... | integer | no | Tag IDs (multi) |
-| `tag_id` | integer | no | Single tag ID (legacy) |
+| `min_speakers`, `max_speakers` | integer | no | Speaker count limits |
+| `hotwords`, `initial_prompt` | string | no | Transcription hints |
+| `transcription_model` | string | no | One of the models the administrator allows |
+| `prompt_variables` | string | no | JSON object of `{{name}}` values for the summary prompt |
| `keep_audio_only` | boolean | no | If `true`, the server discards the video stream and stores only the extracted audio. Lets you upload videos larger than `max_file_size_mb`, up to `max_audio_only_video_size_mb`, as long as the extracted audio fits the regular limit. When `VIDEO_RETENTION` is off at the server, this is implicit for video uploads. |
+The meeting date is chosen in this order: `meeting_date`, a date in the file name (when you turned that on in your settings), `file_last_modified`, the date stored in the file, the upload time.
+
+**Idempotent uploads.** Send an `idempotency_key` (for example a message id and attachment number) when a client may retry. A repeat with the same key by the same user within 24 hours returns the recording the first call created, with `200` and `"idempotent_replay": true`; the file is not stored again and no second transcription is queued. Keys are per user.
+
**Response:**
```json
// 202 Accepted
{
"id": 123,
- "title": "Recording - meeting.mp3",
+ "title": "Weekly sync",
"status": "PENDING",
"created_at": "2024-01-15T10:00:00Z",
"meeting_date": "2024-01-15T09:00:00Z",
+ "participants": "Dana, Omar",
"file_size": 15728640,
"original_filename": "meeting.mp3",
"mime_type": "audio/mpeg",
- "notes": "Quick test upload"
+ "notes": "Quick test upload",
+ "external_refs": [{"id": 77, "system": "mailr", "kind": "event", "ref": "[email protected]", "url": null, "label": null, "created_at": "2024-01-15T10:00:00.000000Z"}],
+ "ignored": {"tag_ids": [], "folder_id": null}
}
```
+`ignored` lists the tags and folder the upload dropped because you cannot use them.
+
**Example:**
```bash
curl -X POST \
- -H "X-API-Token: YOUR_TOKEN" \
+ -H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/audio.mp3" \
- -F "notes=Quick test upload" \
- -F "language=en" \
+ -F "title=Weekly sync" \
+ -F "participants=Dana, Omar" \
+ -F 'external_refs=[{"system":"mailr","kind":"event","ref":"[email protected]"}]' \
+ -F "idempotency_key=msg-4411:part-2" \
https://speakr.example.com/api/v1/recordings/upload
```
@@ -388,6 +408,7 @@ GET /api/v1/recordings
| `date_to` | string | - | Filter to date (ISO format); a date alone includes that whole day |
| `date_field` | string | `created_at` | What `date_from` and `date_to` filter: `created_at` or `meeting_date` |
| `updated_since` | string | - | Only recordings changed after this time (ISO 8601). Deletions are not listed; use the [changes feed](#changes-feed) for those. |
+| `external_system`, `external_ref`, `external_kind` | string | - | Only recordings that carry this [external reference](#external-references) of yours (`external_kind` optional) |
| `tag_id` | integer | - | Filter by tag ID |
| `q` | string | - | Search query (title, participants) |
| `inbox` | boolean | - | Filter by inbox status |
@@ -443,6 +464,56 @@ GET /api/v1/recordings
`updated_at` is the time of the last change a client can see: title, participants, notes, summary, transcript, status, dates, folder, flags, tags, events or sharing. It is present on every recording in API v1 and starts at `created_at`.
+### External References
+
+A reference links a recording to an item in another system, such as a calendar event or a conversation in a mail client. References are private: you see only the ones you added, and a user a recording is shared with sees only their own. Every recording in the API carries your references in `external_refs`.
+
+```json
+{
+ "id": 77,
+ "system": "mailr",
+ "kind": "event",
+ "ref": "[email protected]@2026-10-06T15:00:00Z",
+ "url": "https://mail.example.com/calendar/event/5f1c",
+ "label": "Weekly sync (6 Oct)",
+ "created_at": "2026-10-06T16:02:11.000000Z"
+}
+```
+
+`system` and `kind`: 1 to 40 characters of `a-z`, `0-9`, `_`, `.`, `-`. `ref`: 1 to 500 printable characters. `url`: optional, `http://` or `https://`, at most 1000 characters. `label`: optional, at most 200 characters. At most 50 references per user per recording (`409 conflict`).
+
+```http
+GET /api/v1/recordings/{id}/external-refs
+```
+
+**Scope:** `read`
+
+```http
+POST /api/v1/recordings/{id}/external-refs
+```
+
+**Scope:** `write`
+
+Adds one reference: `201` with the new reference, or `200` with the existing one when you already added the same `system`, `kind` and `ref`.
+
+```http
+PUT /api/v1/recordings/{id}/external-refs?system=mailr
+```
+
+**Scope:** `write`
+
+Replaces your references of that system with `{"external_refs": [...]}` and returns the new list. References of other systems stay.
+
+```http
+DELETE /api/v1/recordings/{id}/external-refs/{ref_id}
+```
+
+**Scope:** `write`
+
+`204`. The writes need edit access to the recording, and a reference change counts as a recording change (`updated_at`, `fields_changed: ["external_refs"]`).
+
+To find recordings by reference, filter the list: `GET /api/v1/recordings?external_system=mailr&external_ref=<ref>`, optionally with `&external_kind=event`.
+
### Changes Feed
```http
diff --git a/src/api/api_v1.py b/src/api/api_v1.py
index ca0fa9a2..b8ddf6dc 100644
--- a/src/api/api_v1.py
+++ b/src/api/api_v1.py
@@ -915,6 +915,8 @@ CAPABILITY_FEATURES = {
'changes_feed': True,
'etags': True,
'webhook_signature_v2': True,
+ 'external_refs': True,
+ 'upload_idempotency': True,
}
# search: {'keyword': True, 'semantic': <Inquire on>} is filled in get_capabilities.
@@ -1007,8 +1009,15 @@ def _updated_at_z(recording):
return iso_z(effective_updated_at(recording))
-def _recording_list_item(r):
- """One recording as GET /recordings lists it; the changes feed uses the same shape."""
+def _recording_list_item(r, refs=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,
@@ -1037,6 +1046,7 @@ def _recording_list_item(r):
'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,
}
@@ -1134,6 +1144,22 @@ def list_recordings():
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': 'external_system and external_ref go together',
+ '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:
@@ -1205,7 +1231,9 @@ def list_recordings():
pagination = query.paginate(page=page, per_page=per_page, error_out=False)
# Build response
- recordings = [_recording_list_item(r) for r in pagination.items]
+ from src.services.external_refs import refs_map
+ page_refs = refs_map([r.id for r in pagination.items], current_user.id)
+ recordings = [_recording_list_item(r, page_refs.get(r.id, [])) for r in pagination.items]
return jsonify({
'recordings': recordings,
@@ -1325,6 +1353,82 @@ def search_recordings_v1():
'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': 'Recording not found', 'code': 'not_found'}), 404)
+ if not has_recording_access(recording, current_user, require_edit=require_edit):
+ return None, (jsonify({'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': 'Reference not found', 'code': 'not_found'}), 404
+ db.session.delete(row)
+ db.session.commit()
+ return '', 204
+
+
@api_v1_bp.route('/recordings/changes', methods=['GET'])
@require_scope('read')
@login_required
@@ -1355,10 +1459,12 @@ def list_recording_changes():
return jsonify({'error': 'The cursor is too old; start again without a cursor',
'code': 'cursor_expired'}), 410
items, next_cursor, has_more = read_changes(current_user.id, cursor=cursor, limit=limit)
+ from src.services.external_refs import refs_map
+ page_refs = refs_map([obj.id for kind, obj in items if kind == 'upsert'], current_user.id)
changes = []
for kind, obj in items:
if kind == 'upsert':
- changes.append({'type': 'upsert', 'recording': _recording_list_item(obj)})
+ changes.append({'type': 'upsert', 'recording': _recording_list_item(obj, page_refs.get(obj.id, []))})
else:
changes.append({'type': 'delete', 'id': obj.recording_id,
'deleted_at': iso_z(obj.deleted_at), 'reason': obj.reason})
@@ -1418,6 +1524,8 @@ def get_recording(recording_id):
'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
@@ -3368,5 +3476,81 @@ def upload_recording():
- 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)
"""
- return _upload_file_ui()
+ 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': 'participants must be at most 500 characters', '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': 'idempotency_key must be 1 to 100 characters', 'code': 'invalid_parameter'}), 400
+ if key:
+ earlier = (Recording.query
+ .filter(Recording.user_id == current_user.id, Recording.upload_idempotency_key == key,
+ Recording.created_at >= datetime.utcnow() - timedelta(hours=24))
+ .order_by(Recording.id.desc()).first())
+ if earlier is not 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
+
+ # 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': 'A tag or folder in the upload is not one you can use',
+ '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)
+ 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
diff --git a/src/api/recordings.py b/src/api/recordings.py
index 966a16a0..22735e39 100644
--- a/src/api/recordings.py
+++ b/src/api/recordings.py
@@ -2150,8 +2150,14 @@ def ingest_uploaded_recording(
processing_source='upload',
success_status=202,
reuse_duplicate=False,
+ prepare=None,
):
- """Run an uploaded file through Speakr's standard ingestion pipeline."""
+ """Run an uploaded file through Speakr's standard ingestion pipeline.
+
+ prepare(recording), when given, runs before the recording is first
+ committed, so fields it sets (API v1 participants, references, the
+ idempotency key) arrive with the recording itself.
+ """
try:
if uploaded_file is None:
return jsonify({'error': 'No file provided'}), 400
@@ -2767,6 +2773,9 @@ def ingest_uploaded_recording(
)
db.session.add(new_association)
+ if prepare is not None:
+ prepare(recording)
+
db.session.commit()
if selected_tags:
diff --git a/src/init_db.py b/src/init_db.py
index 15c0ef92..b05f5195 100644
--- a/src/init_db.py
+++ b/src/init_db.py
@@ -258,6 +258,10 @@ def _run_migrations(app, engine):
run_once(engine, '0002_backfill_recording_updated_at', _backfill_recording_updated_at,
logger=app.logger)
+ # Idempotent API uploads (mailr spec G8).
+ if add_column_if_not_exists(engine, 'recording', 'upload_idempotency_key', 'VARCHAR(100)'):
+ app.logger.info("Added upload_idempotency_key column to recording table")
+ create_index_if_not_exists(engine, 'ix_recording_user_idem', 'recording', 'user_id, upload_idempotency_key')
if add_column_if_not_exists(engine, 'recording', 'processing_time_seconds', 'INTEGER'):
app.logger.info("Added processing_time_seconds column to recording table")
if add_column_if_not_exists(engine, 'recording', 'transcription_duration_seconds', 'INTEGER'):
diff --git a/src/models/__init__.py b/src/models/__init__.py
index f50713d4..7639c62b 100644
--- a/src/models/__init__.py
+++ b/src/models/__init__.py
@@ -19,6 +19,7 @@ from .voice import VoiceEmbeddingSpace, SpeakerVoiceSample
from .api_token import APIToken
from .speaker_snippet import SpeakerSnippet
from .recording import Recording, RecordingTombstone, TranscriptChunk
+from .external_ref import RecordingExternalRef
from .sharing import Share, InternalShare, SharedRecordingState
from .organization import Group, GroupMembership, Tag, RecordingTag, Folder
from .events import Event
@@ -61,7 +62,7 @@ __all__ = [
'SpeakerSnippet',
# Recording models
'Recording',
- 'TranscriptChunk', 'RecordingTombstone',
+ 'TranscriptChunk', 'RecordingTombstone', 'RecordingExternalRef',
# Sharing models
'Share',
'InternalShare',
diff --git a/src/models/external_ref.py b/src/models/external_ref.py
new file mode 100644
index 00000000..c8708b4f
--- /dev/null
+++ b/src/models/external_ref.py
@@ -0,0 +1,43 @@
+"""External references: a link from a recording to an item in another system
+(mailr spec G8), for example a mailr calendar event or conversation.
+
+References are private per user: each user sees and writes only their own,
+on recordings they can read.
+"""
+
+from datetime import datetime
+
+from src.database import db
+
+
+class RecordingExternalRef(db.Model):
+ __tablename__ = 'recording_external_ref'
+
+ id = db.Column(db.Integer, primary_key=True)
+ recording_id = db.Column(db.Integer, db.ForeignKey('recording.id', ondelete='CASCADE'),
+ nullable=False, index=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('user.id', ondelete='CASCADE'), nullable=False)
+ system = db.Column(db.String(40), nullable=False)
+ kind = db.Column(db.String(40), nullable=False)
+ ref = db.Column(db.String(500), nullable=False)
+ url = db.Column(db.String(1000), nullable=True)
+ label = db.Column(db.String(200), nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+ __table_args__ = (
+ db.UniqueConstraint('recording_id', 'user_id', 'system', 'kind', 'ref', name='uq_recording_external_ref'),
+ db.Index('ix_external_ref_user_system_ref', 'user_id', 'system', 'ref'),
+ )
+
+ def to_dict(self):
+ z = lambda v: v.strftime('%Y-%m-%dT%H:%M:%S.%fZ') if v else None
+ return {
+ 'id': self.id,
+ 'system': self.system,
+ 'kind': self.kind,
+ 'ref': self.ref,
+ 'url': self.url,
+ 'label': self.label,
+ 'created_at': z(self.created_at),
+ }
diff --git a/src/models/recording.py b/src/models/recording.py
index 4cf212f6..48eeeb97 100644
--- a/src/models/recording.py
+++ b/src/models/recording.py
@@ -51,6 +51,9 @@ class Recording(db.Model):
# Last change a client can see (mailr spec G2); set by the before_flush
# listener in src/services/recording_changes.py, never by hand.
updated_at = db.Column(db.DateTime, nullable=True, index=True)
+ # API upload retries (mailr spec G8): a repeat with the same key by the same
+ # user within 24 hours returns this recording.
+ upload_idempotency_key = db.Column(db.String(100), nullable=True)
processing_time_seconds = db.Column(db.Integer, nullable=True)
transcription_duration_seconds = db.Column(db.Integer, nullable=True) # Time taken for transcription
# Cached audio duration in seconds, populated at transcription
diff --git a/src/services/external_refs.py b/src/services/external_refs.py
new file mode 100644
index 00000000..fb68936c
--- /dev/null
+++ b/src/services/external_refs.py
@@ -0,0 +1,99 @@
+"""Validation and storage of external references (mailr spec G8)."""
+
+import re
+
+from src.database import db
+
+MAX_PER_RECORDING = 50
+_SLUG = re.compile(r'^[a-z0-9_.-]{1,40}$')
+
+
+class RefError(ValueError):
+ def __init__(self, message, code='invalid_parameter', status=400):
+ super().__init__(message)
+ self.code = code
+ self.status = status
+
+
+def validate(raw):
+ """A clean ref dict from client input, or RefError."""
+ if not isinstance(raw, dict):
+ raise RefError('Each external reference must be an object')
+ system = raw.get('system')
+ kind = raw.get('kind')
+ ref = raw.get('ref')
+ url = raw.get('url')
+ label = raw.get('label')
+ if not isinstance(system, str) or not _SLUG.match(system):
+ raise RefError('system must be 1 to 40 characters of a-z, 0-9, _ . -')
+ if not isinstance(kind, str) or not _SLUG.match(kind):
+ raise RefError('kind must be 1 to 40 characters of a-z, 0-9, _ . -')
+ if not isinstance(ref, str) or not 1 <= len(ref) <= 500 or not ref.isprintable():
+ raise RefError('ref must be 1 to 500 printable characters')
+ if url is not None:
+ if not isinstance(url, str) or len(url) > 1000 or not re.match(r'^https?://\S+$', url, re.I):
+ raise RefError('url must be an http:// or https:// address of at most 1000 characters')
+ if label is not None and (not isinstance(label, str) or len(label) > 200):
+ raise RefError('label must be at most 200 characters')
+ return {'system': system, 'kind': kind, 'ref': ref, 'url': url or None, 'label': label or None}
+
+
+def validate_list(raw_list):
+ if not isinstance(raw_list, list):
+ raise RefError('external_refs must be a list')
+ if len(raw_list) > MAX_PER_RECORDING:
+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)
+ return [validate(r) for r in raw_list]
+
+
+def refs_for(recording_id, user_id):
+ from src.models import RecordingExternalRef
+ return (RecordingExternalRef.query.filter_by(recording_id=recording_id, user_id=user_id)
+ .order_by(RecordingExternalRef.id).all())
+
+
+def refs_map(recording_ids, user_id):
+ """{recording id: [ref dict]} for one page of recordings, in one query."""
+ from src.models import RecordingExternalRef
+ result = {rid: [] for rid in recording_ids}
+ if not recording_ids:
+ return result
+ for ref in (RecordingExternalRef.query
+ .filter(RecordingExternalRef.recording_id.in_(list(recording_ids)),
+ RecordingExternalRef.user_id == user_id)
+ .order_by(RecordingExternalRef.id)):
+ result.setdefault(ref.recording_id, []).append(ref.to_dict())
+ return result
+
+
+def add(recording, user_id, clean):
+ """(ref, created). An existing (system, kind, ref) is returned unchanged."""
+ from src.models import RecordingExternalRef
+ existing = RecordingExternalRef.query.filter_by(
+ recording_id=recording.id, user_id=user_id, system=clean['system'], kind=clean['kind'],
+ ref=clean['ref']).first()
+ if existing is not None:
+ return existing, False
+ if RecordingExternalRef.query.filter_by(recording_id=recording.id, user_id=user_id).count() >= MAX_PER_RECORDING:
+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)
+ row = RecordingExternalRef(recording_id=recording.id, user_id=user_id, **clean)
+ db.session.add(row)
+ return row, True
+
+
+def replace_system(recording, user_id, system, cleans):
+ """Replace this user's refs of one system on the recording."""
+ from src.models import RecordingExternalRef
+ if any(c['system'] != system for c in cleans):
+ raise RefError('Every reference must have the system given in ?system=')
+ others = RecordingExternalRef.query.filter(
+ RecordingExternalRef.recording_id == recording.id, RecordingExternalRef.user_id == user_id,
+ RecordingExternalRef.system != system).count()
+ unique = {(c['kind'], c['ref']): c for c in cleans}
+ if others + len(unique) > MAX_PER_RECORDING:
+ raise RefError(f'At most {MAX_PER_RECORDING} external references per recording', code='conflict', status=409)
+ for row in RecordingExternalRef.query.filter_by(recording_id=recording.id, user_id=user_id, system=system):
+ db.session.delete(row)
+ db.session.flush()
+ for c in unique.values():
+ db.session.add(RecordingExternalRef(recording_id=recording.id, user_id=user_id, **c))
diff --git a/src/services/webhook_dispatch.py b/src/services/webhook_dispatch.py
index cc90cd7c..7f632bfa 100644
--- a/src/services/webhook_dispatch.py
+++ b/src/services/webhook_dispatch.py
@@ -407,7 +407,7 @@ def emit_webhook_event(user_id: int, event_type: str, data: dict, *, app=None) -
return _do_enqueue()
-def _with_updated_at(session, event_type, data):
+def _with_updated_at(session, event_type, data, user_id=None):
"""data of a recording.* event carries the recording's updated_at (spec W4)."""
data = dict(data or {})
if event_type.startswith('recording.') and 'updated_at' not in data and data.get('recording_id'):
@@ -415,6 +415,11 @@ def _with_updated_at(session, event_type, data):
rec = session.get(Recording, data['recording_id'])
if rec is not None:
data['updated_at'] = rec.updated_at_z()
+ if event_type.startswith('recording.') and event_type != 'recording.deleted' and data.get('recording_id') \
+ and 'external_refs' not in data:
+ from src.models import RecordingExternalRef
+ data['external_refs'] = [r.to_dict() for r in session.query(RecordingExternalRef).filter_by(
+ recording_id=data['recording_id'], user_id=user_id).order_by(RecordingExternalRef.id)]
return data
@@ -447,7 +452,7 @@ def enqueue_event(session, user_id, event_type, data):
matched = [w for w in subscriptions if event_type in w.event_list]
if not matched:
return 0
- data = _with_updated_at(session, event_type, data)
+ data = _with_updated_at(session, event_type, data, user_id)
event_id = str(uuid.uuid4())
first_attempt_at = datetime.utcnow()
created = 0
diff --git a/tests/test_api_v1_external_refs.py b/tests/test_api_v1_external_refs.py
new file mode 100644
index 00000000..9a8a8fd4
--- /dev/null
+++ b/tests/test_api_v1_external_refs.py
@@ -0,0 +1,272 @@
+"""External references and the new upload fields (mailr spec G8).
+
+A reference links a recording to an item in another system and belongs to
+one user: the owner and a share recipient each see only their own. The API
+upload takes participants, references, an idempotency key and strict mode.
+
+SHARED-DB: users, tokens, tags, folders, shares, webhooks, recordings and
+stored media are removed afterwards.
+"""
+
+import io
+import json
+import os
+import secrets
+import sys
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.app import app, db
+from src.models import (APIToken, Folder, InternalShare, Recording, RecordingExternalRef, RecordingTag, Tag,
+ User, Webhook, WebhookDelivery)
+from src.utils.token_auth import hash_token
+
+EVENT = {"system": "mailr", "kind": "event", "ref": "[email protected]@2026-10-06T15:00:00Z",
+ "url": "https://mail.example.com/calendar/event/5f1c", "label": "Weekly sync (6 Oct)"}
+
+
+def world():
+ with app.app_context():
+ s = secrets.token_hex(4)
+ owner = User(username=f"xr_{s}", email=f"xr_{s}@local.test", password="x")
+ guest = User(username=f"xrg_{s}", email=f"xrg_{s}@local.test", password="x")
+ db.session.add_all([owner, guest])
+ db.session.commit()
+ rec = Recording(user_id=owner.id, title="Sync", status="COMPLETED", original_filename="s.wav")
+ mine = Tag(name=f"mine-{s}", user_id=owner.id)
+ theirs = Tag(name=f"theirs-{s}", user_id=guest.id)
+ folder = Folder(name=f"f-{s}", user_id=owner.id)
+ db.session.add_all([rec, mine, theirs, folder])
+ db.session.commit()
+ db.session.add(InternalShare(recording_id=rec.id, owner_id=owner.id, shared_with_user_id=guest.id, can_edit=True))
+ tokens = {}
+ for who in (owner, guest):
+ p = f"tok-{secrets.token_urlsafe(16)}"
+ db.session.add(APIToken(user_id=who.id, token_hash=hash_token(p), name="xr"))
+ tokens[who.id] = p
+ db.session.commit()
+ ids = dict(owner=owner.id, guest=guest.id, rec=rec.id, mine=mine.id, theirs=theirs.id, folder=folder.id,
+ tokens=tokens)
+ with patch("src.app.ENABLE_INTERNAL_SHARING", True):
+ yield ids
+ with app.app_context():
+ db.session.rollback()
+ users = [ids["owner"], ids["guest"]]
+ recs = [r.id for r in Recording.query.filter(Recording.user_id.in_(users))]
+ from src.services.storage import get_storage_service
+ for r in Recording.query.filter(Recording.id.in_(recs)):
+ if r.audio_path:
+ try:
+ get_storage_service().delete(r.audio_path, missing_ok=True)
+ except Exception:
+ pass
+ RecordingExternalRef.query.filter(RecordingExternalRef.user_id.in_(users)).delete(synchronize_session=False)
+ RecordingTag.query.filter(RecordingTag.recording_id.in_(recs)).delete(synchronize_session=False)
+ InternalShare.query.filter(InternalShare.recording_id.in_(recs)).delete(synchronize_session=False)
+ hooks = [w.id for w in Webhook.query.filter(Webhook.user_id.in_(users))]
+ WebhookDelivery.query.filter(WebhookDelivery.webhook_id.in_(hooks)).delete(synchronize_session=False)
+ Webhook.query.filter(Webhook.id.in_(hooks)).delete(synchronize_session=False)
+ from src.models import ProcessingJob
+ ProcessingJob.query.filter(ProcessingJob.recording_id.in_(recs)).delete(synchronize_session=False)
+ Recording.query.filter(Recording.id.in_(recs)).delete(synchronize_session=False)
+ Tag.query.filter(Tag.user_id.in_(users)).delete(synchronize_session=False)
+ Folder.query.filter(Folder.user_id.in_(users)).delete(synchronize_session=False)
+ APIToken.query.filter(APIToken.user_id.in_(users)).delete(synchronize_session=False)
+ User.query.filter(User.id.in_(users)).delete(synchronize_session=False)
+ db.session.commit()
+
+
+def _h(world, who="owner"):
+ return {"Authorization": f"Bearer {world['tokens'][world[who]]}"}
+
+
+def _url(world, suffix=""):
+ return f"/api/v1/recordings/{world['rec']}/external-refs{suffix}"
+
+
+# ------------------------------------------------------------ refs
+
+def test_create_is_idempotent_and_listed(world):
+ with app.test_client() as c:
+ first = c.post(_url(world), json=EVENT, headers=_h(world))
+ again = c.post(_url(world), json=EVENT, headers=_h(world))
+ listed = c.get(_url(world), headers=_h(world)).get_json()["external_refs"]
+ detail = c.get(f"/api/v1/recordings/{world['rec']}", headers=_h(world)).get_json()
+ assert first.status_code == 201 and again.status_code == 200
+ assert again.get_json()["id"] == first.get_json()["id"]
+ assert [r["ref"] for r in listed] == [EVENT["ref"]] and listed[0]["created_at"].endswith("Z")
+ assert [r["id"] for r in detail["external_refs"]] == [first.get_json()["id"]]
+
+
+def test_replace_by_system_and_delete(world):
+ with app.test_client() as c:
+ c.post(_url(world), json=dict(EVENT, system="other"), headers=_h(world))
+ c.post(_url(world), json=EVENT, headers=_h(world))
+ replaced = c.put(_url(world, "?system=mailr"), headers=_h(world), json={"external_refs": [
+ {"system": "mailr", "kind": "conversation", "ref": "conv-1"},
+ {"system": "mailr", "kind": "conversation", "ref": "conv-1"}]})
+ refs = replaced.get_json()["external_refs"]
+ assert replaced.status_code == 200
+ assert sorted((r["system"], r["ref"]) for r in refs) == [("mailr", "conv-1"), ("other", EVENT["ref"])]
+ mixed = c.put(_url(world, "?system=mailr"), headers=_h(world),
+ json={"external_refs": [dict(EVENT, system="other")]})
+ assert mixed.status_code == 400
+ conv = next(r for r in refs if r["ref"] == "conv-1")
+ assert c.delete(_url(world, f"/{conv['id']}"), headers=_h(world)).status_code == 204
+ assert c.delete(_url(world, f"/{conv['id']}"), headers=_h(world)).status_code == 404
+
+
+def test_list_filter_by_ref(world):
+ with app.test_client() as c:
+ c.post(_url(world), json=EVENT, headers=_h(world))
+ found = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}",
+ headers=_h(world)).get_json()["recordings"]
+ kind = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}&external_kind=conversation",
+ headers=_h(world)).get_json()["recordings"]
+ lone = c.get("/api/v1/recordings?external_system=mailr", headers=_h(world))
+ assert [r["id"] for r in found] == [world["rec"]] and found[0]["external_refs"][0]["ref"] == EVENT["ref"]
+ assert kind == [] and lone.status_code == 400
+
+
+def test_refs_are_private_per_user(world):
+ with app.test_client() as c:
+ assert c.post(_url(world), json=EVENT, headers=_h(world)).status_code == 201
+ assert c.get(_url(world), headers=_h(world, "guest")).get_json()["external_refs"] == []
+ mine = c.post(_url(world), json=dict(EVENT, ref="guest-own"), headers=_h(world, "guest")).get_json()
+ assert [r["ref"] for r in c.get(_url(world), headers=_h(world)).get_json()["external_refs"]] == [EVENT["ref"]]
+ owner_ref = c.get(_url(world), headers=_h(world)).get_json()["external_refs"][0]["id"]
+ assert c.delete(_url(world, f"/{owner_ref}"), headers=_h(world, "guest")).status_code == 404
+ assert mine["ref"] == "guest-own"
+
+
+def test_the_limit_is_fifty(world):
+ with app.app_context():
+ for i in range(50):
+ db.session.add(RecordingExternalRef(recording_id=world["rec"], user_id=world["owner"],
+ system="mailr", kind="k", ref=f"r{i}"))
+ db.session.commit()
+ with app.test_client() as c:
+ resp = c.post(_url(world), json=EVENT, headers=_h(world))
+ assert resp.status_code == 409 and resp.get_json()["code"] == "conflict"
+
+
+ dict(EVENT, url="javascript:alert(1)"), dict(EVENT, url="ftp://x"), dict(EVENT, system="Mailr"),
+ dict(EVENT, kind=""), dict(EVENT, ref=""), dict(EVENT, ref="x" * 501), dict(EVENT, label="x" * 201),
+])
+def test_validation(world, bad):
+ with app.test_client() as c:
+ resp = c.post(_url(world), json=bad, headers=_h(world))
+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"
+
+
+def test_a_ref_change_moves_updated_at_and_fires_a_webhook(world):
+ with app.app_context():
+ r = db.session.get(Recording, world["rec"])
+ r.updated_at = datetime(2020, 1, 1)
+ hook = Webhook(user_id=world["owner"], name="m", url="https://example.com/h", secret="s" * 40,
+ events=json.dumps(["recording.updated"]))
+ db.session.add(hook)
+ db.session.commit()
+ hook_id = hook.id
+ with app.test_client() as c:
+ c.post(_url(world), json=EVENT, headers=_h(world))
+ with app.app_context():
+ assert db.session.get(Recording, world["rec"]).updated_at > datetime(2025, 1, 1)
+ payloads = [json.loads(d.payload)["data"] for d in WebhookDelivery.query.filter_by(webhook_id=hook_id)]
+ assert [p["fields_changed"] for p in payloads] == [["external_refs"]]
+ assert [x["ref"] for x in payloads[0]["external_refs"]] == [EVENT["ref"]]
+
+
+# ------------------------------------------------------------ upload
+
+@contextmanager
+def _no_media_tools():
+ def _convert(filepath, **kwargs):
+ r = MagicMock()
+ r.output_path = filepath
+ r.was_converted = r.was_compressed = False
+ r.original_codec = r.final_codec = "opus"
+ r.size_reduction_percent = 0.0
+ return r
+ with patch("src.api.recordings.convert_if_needed", side_effect=_convert), \
+ patch("src.api.recordings.get_codec_info",
+ return_value={"has_video": False, "audio_codec": "opus", "video_codec": None, "duration": 5.0}), \
+ patch("src.api.recordings.get_duration", return_value=5.0), \
+ patch("src.api.recordings.get_creation_date", return_value=None), \
+ patch("src.services.job_queue.job_queue.enqueue", return_value=1) as enqueue:
+ yield enqueue
+
+
+def _upload(world, who="owner", payload=b"audio", **fields):
+ data = {"file": (io.BytesIO(payload + secrets.token_bytes(8)), "memo.webm")}
+ data.update(fields)
+ with app.test_client() as c:
+ return c.post("/api/v1/recordings/upload", data=data, headers=_h(world, who),
+ content_type="multipart/form-data")
+
+
+def test_an_upload_with_every_field(world):
+ with _no_media_tools():
+ resp = _upload(world, title="Weekly sync", participants="Dana, Omar", meeting_date="2026-10-06T15:00:00Z",
+ folder_id=str(world["folder"]), **{"tag_ids[0]": str(world["mine"])},
+ external_refs=json.dumps([EVENT]), idempotency_key="msg-1:part-2")
+ body = resp.get_json()
+ assert resp.status_code == 202, body
+ assert body["ignored"] == {"tag_ids": [], "folder_id": None}
+ assert [r["ref"] for r in body["external_refs"]] == [EVENT["ref"]]
+ with app.test_client() as c:
+ listed = c.get(f"/api/v1/recordings?external_system=mailr&external_ref={EVENT['ref']}",
+ headers=_h(world)).get_json()["recordings"]
+ item = next(r for r in listed if r["id"] == body["id"])
+ assert (item["title"], item["participants"], item["folder_id"]) == ("Weekly sync", "Dana, Omar", world["folder"])
+ assert item["meeting_date"].startswith("2026-10-06T15:00:00") and [t["id"] for t in item["tags"]] == [world["mine"]]
+
+
+def test_a_repeat_with_the_same_key_creates_nothing(world):
+ with _no_media_tools() as enqueue:
+ first = _upload(world, idempotency_key="msg-9")
+ second = _upload(world, idempotency_key="msg-9")
+ assert enqueue.call_count == 1
+ assert second.status_code == 200 and second.get_json()["idempotent_replay"] is True
+ assert second.get_json()["id"] == first.get_json()["id"]
+ with app.app_context():
+ assert Recording.query.filter_by(user_id=world["owner"], upload_idempotency_key="msg-9").count() == 1
+ with _no_media_tools():
+ other_user = _upload(world, who="guest", idempotency_key="msg-9")
+ assert other_user.get_json()["id"] != first.get_json()["id"]
+
+
+def test_an_old_key_does_not_replay(world):
+ with _no_media_tools():
+ first = _upload(world, idempotency_key="msg-old")
+ with app.app_context():
+ r = db.session.get(Recording, first.get_json()["id"])
+ r.created_at = datetime.utcnow() - timedelta(hours=25)
+ db.session.commit()
+ with _no_media_tools():
+ second = _upload(world, idempotency_key="msg-old")
+ assert second.status_code == 202 and second.get_json()["id"] != first.get_json()["id"]
+
+
+def test_strict_and_lenient_tags(world):
+ with _no_media_tools():
+ strict = _upload(world, strict="true", **{"tag_ids[0]": str(world["theirs"])})
+ lenient = _upload(world, **{"tag_ids[0]": str(world["theirs"]), "tag_ids[1]": str(world["mine"])})
+ assert strict.status_code == 400 and strict.get_json()["ignored"]["tag_ids"] == [world["theirs"]]
+ assert lenient.status_code == 202 and lenient.get_json()["ignored"]["tag_ids"] == [world["theirs"]]
+
+
[email protected]("fields", [{"participants": "x" * 501}, {"external_refs": "not json"},
+ {"external_refs": json.dumps([dict(EVENT, url="javascript:x")])},
+ {"idempotency_key": "k" * 101}])
+def test_bad_upload_fields(world, fields):
+ with _no_media_tools():
+ resp = _upload(world, **fields)
+ assert resp.status_code == 400 and resp.get_json()["code"] == "invalid_parameter"
diff --git a/tests/test_api_v1_scope_coverage.py b/tests/test_api_v1_scope_coverage.py
index 95c23467..5e39cb47 100644
--- a/tests/test_api_v1_scope_coverage.py
+++ b/tests/test_api_v1_scope_coverage.py
@@ -13,11 +13,11 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from src.app import app
EXPECTED = {
- "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "search_recordings_v1", "get_recording",
+ "read": {"get_openapi_spec", "get_docs", "get_stats", "get_current_user", "list_recordings", "list_recording_changes", "search_recordings_v1", "list_external_refs", "get_recording",
"get_transcript", "get_summary", "get_notes", "get_recording_status", "list_tags", "list_folders",
"get_folder", "get_transcription_info", "list_speakers", "get_recording_speakers",
"get_recording_events", "download_events_ics", "download_audio"},
- "write": {"update_recording", "replace_notes", "replace_summary", "create_tag", "update_tag",
+ "write": {"add_external_ref", "replace_external_refs", "delete_external_ref", "update_recording", "replace_notes", "replace_summary", "create_tag", "update_tag",
"add_tags_to_recording", "remove_tag_from_recording", "create_folder", "update_folder",
"create_speaker", "update_speaker", "assign_speakers", "batch_update_recordings"},
"account": {"update_auto_summarization"},
diff --git a/tests/test_upgrade_mailr_api.py b/tests/test_upgrade_mailr_api.py
index 409c10dc..57bc3a07 100644
--- a/tests/test_upgrade_mailr_api.py
+++ b/tests/test_upgrade_mailr_api.py
@@ -137,3 +137,17 @@ def test_webhook_rotation_grace_columns(tmp_path, fixture):
con.close()
assert row == ("s" * 40, None, None)
+
[email protected]("fixture", FIXTURES, ids=[f[:-4] for f in FIXTURES])
+def test_upload_idempotency_and_external_refs(tmp_path, fixture):
+ """G8: the idempotency column and index, and the reference table."""
+ db_path, con = _load(tmp_path, fixture)
+ con.close()
+ _upgrade(db_path)
+ _upgrade(db_path)
+ con = sqlite3.connect(db_path)
+ assert "upload_idempotency_key" in _columns(con, "recording")
+ assert "ix_recording_user_idem" in {r[1] for r in con.execute("PRAGMA index_list('recording')")}
+ assert {"recording_id", "user_id", "system", "kind", "ref", "url", "label"} <= _columns(con, "recording_external_ref")
+ con.close()
+