WordloopContracts
API contract reference for the Meeting Recording bet — organised by entity, covering REST, WebSocket, and Pub/Sub.
Contracts
These contracts define the complete API surface for the Meeting Recording bet. Each page covers one entity end-to-end: its resource shape, REST operations, WebSocket events, ML integration, and Pub/Sub triggers — so you can understand how a single concept works across all protocols without jumping between files.
For shared concerns that apply across all entities — connection semantics, authentication, error format, CloudEvents envelope, Pub/Sub configuration, and failure modes — see Infrastructure.
Specification alignment: existing machine-readable specs live in specs/core-openapi.json, specs/ml-openapi.json, specs/core-asyncapi-ws.yaml, and specs/core-asyncapi-pubsub.yaml. These contract pages describe the ideal-state surface — both existing endpoints and new additions for live recording. New endpoints and fields introduced by this bet are marked with New.
Entity Pages
| Entity | What it covers |
|---|---|
| Meeting | Top-level resource. CRUD, expand parameter, speaker-label assignment, audio playback URL. |
| Recording | Live recording lifecycle. WebSocket commands and events, ML session management, OPFS gap repair, Pub/Sub drain. |
| Audio | Binary audio transport. Frame formats (browser→Core, Core→ML), chunk storage, acknowledgement, backpressure. |
| Transcription | Transcript segments. CRUD, live streaming events, batch processing, ML write-back, Pub/Sub trigger. |
| Synthesis | ML-generated artefacts. Summary, topics, talking points. Read endpoints and ML write-back. |
| Task | Action items. Full CRUD with sub-task nesting. User-created and system-generated (ML). |
| Person | Speaker identity. CRUD, speaker identification pipeline, voice profiles, ML matching events. |
ML → Core Write-Back Summary
ML writes durable meeting artefacts to Core REST, not to the browser and not directly to Core's database. Each write-back endpoint is documented on its entity page.
| ML output | Core REST target | Entity page |
|---|---|---|
| Headline | PATCH /meetings/{id} | Meeting |
| Live transcript append | POST /transcriptions/{id}/segments | Transcription |
| Batch transcript replacement | PUT /transcriptions/{id}/segments | Transcription |
| Transcription lifecycle | PATCH /transcriptions/{id}/status | Transcription |
| Live talking point | POST /meetings/{id}/talking-points | Synthesis |
| Final synthesis | PUT /meetings/{id}/synthesis | Synthesis |
| System-generated tasks | POST /tasks | Task |
Open Problem: ML→Core Write-Back Resilience
If Core is unavailable when ML finishes post-meeting processing, ML cannot deliver results (transcript segments, synthesis, status updates). Today, ML retries with exponential backoff against Core REST. If Core remains down beyond the retry budget, the results are lost.
This is documented as a separate problem statement for a future bet. Potential approaches include ML publishing results to Pub/Sub as a durable fallback, or persisting results to its own store for later delivery.