{ "openapi": "3.0.4", "info": { "title": "Wavesift API", "description": "Client-facing API: upload recordings, read transcripts, generate summaries. Authenticate with `X-Api-Key` (create a key from a login session via POST /v1/user/api-keys) or with `Authorization: Bearer` after POST /v1/auth/login.", "version": "v1" }, "paths": { "/v1/user/api-keys": { "post": { "tags": [ "ApiKeys" ], "summary": "Create an API key for the current account", "description": "Requires a login session (JWT); requests authenticated with an API key are rejected with 403. The raw key is returned ONCE in `apiKey`, only its hash is stored. Up to 5 active keys per account. Keys inherit the account's plan limits.", "operationId": "CreateOwnApiKey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiKeyIssuedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden" }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "get": { "tags": [ "ApiKeys" ], "summary": "List the current account's API keys, newest first", "operationId": "ListOwnApiKeys", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiKeyListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/api-keys/{id}": { "delete": { "tags": [ "ApiKeys" ], "summary": "Revoke one of the current account's API keys (immediate, irreversible)", "operationId": "RevokeOwnApiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientApiKeyDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Authenticate with email and password, issue access + refresh tokens", "operationId": "Login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new account, issue access + refresh tokens", "operationId": "Register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Rotate refresh token, issue a new access token", "operationId": "RefreshTokens", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Revoke refresh token and clear auth cookies", "operationId": "Logout", "responses": { "200": { "description": "OK" } } } }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Public lightweight liveness probe for Client/Agent apps", "description": "Returns 200 as long as the server accepts requests. Does not touch the database or downstream services — those have their own checks.", "operationId": "GetHealth", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthDto" } } } } } } }, "/v1/subscription/current": { "get": { "tags": [ "Subscription" ], "summary": "Current plan + limits + usage for this billing period", "description": "Primary API for the Flutter client: render remaining audio minutes, preset slots, upload file-size cap. Auto-provisions the default plan on first call.", "operationId": "GetCurrentSubscription", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUsageDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/subscription/plans": { "get": { "tags": [ "Subscription" ], "summary": "All enabled subscription plans (for the upgrade screen)", "operationId": "ListSubscriptionPlans", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPlanListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{transcriptionId}/summaries": { "post": { "tags": [ "Summaries" ], "summary": "Queue a summary generation for a completed transcription", "description": "Uses an accessible preset (enabled global or own). The preset name and prompt are snapshotted, so the history stays intact when presets are edited later. Stream progress via /summaries/{id}/events.", "operationId": "GenerateSummary", "parameters": [ { "name": "transcriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSummary" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryDto" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "get": { "tags": [ "Summaries" ], "summary": "Generation history of a transcription, newest first", "operationId": "ListSummaries", "parameters": [ { "name": "transcriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryListDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/summaries/{id}": { "get": { "tags": [ "Summaries" ], "summary": "Get one summary with markdown result", "operationId": "GetSummary", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/summaries/{id}/events": { "get": { "tags": [ "Summaries" ], "summary": "Server-sent events with generation status and streamed tokens", "description": "Starts with a snapshot 'status' event, then streams 'token' events live until the terminal status. On reconnect the tokens sent so far are not replayed — fetch the summary once it completes.", "operationId": "StreamSummaryEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/summary-presets": { "get": { "tags": [ "SummaryPresets" ], "summary": "List available summary presets (enabled global + own)", "operationId": "ListSummaryPresets", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPresetListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "post": { "tags": [ "SummaryPresets" ], "summary": "Create an own summary preset", "operationId": "CreateSummaryPreset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSummaryPreset" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPresetDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/summary-presets/{id}": { "put": { "tags": [ "SummaryPresets" ], "summary": "Update an own summary preset", "operationId": "UpdateSummaryPreset", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSummaryPreset" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPresetDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "delete": { "tags": [ "SummaryPresets" ], "summary": "Delete an own summary preset (soft delete)", "operationId": "DeleteSummaryPreset", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions": { "post": { "tags": [ "Transcriptions" ], "summary": "Upload audio (mic and/or system track) and queue a transcription", "description": "Multipart form: mic_file and/or system_file (at least one), optional title, external_id, language (ISO code or 'auto'), mic_offset_ms, system_offset_ms. external_id makes the upload idempotent per account: a repeated upload with the same external_id returns the existing transcription instead of creating another one. Returns the queued transcription; progress is available via SSE /events or by polling.", "operationId": "CreateTranscription", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "mic_file": { "type": "string", "format": "binary" }, "system_file": { "type": "string", "format": "binary" }, "title": { "type": "string" }, "external_id": { "type": "string" }, "language": { "type": "string" }, "mic_offset_ms": { "type": "integer", "format": "int32" }, "system_offset_ms": { "type": "integer", "format": "int32" } } }, "encoding": { "mic_file": { "style": "form" }, "system_file": { "style": "form" }, "title": { "style": "form" }, "external_id": { "style": "form" }, "language": { "style": "form" }, "mic_offset_ms": { "style": "form" }, "system_offset_ms": { "style": "form" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "get": { "tags": [ "Transcriptions" ], "summary": "List own transcriptions (paginated)", "operationId": "ListTranscriptions", "parameters": [ { "name": "status", "in": "query", "schema": { "enum": [ "queued", "processing", "completed", "failed" ], "type": "string" } }, { "name": "kind", "in": "query", "schema": { "enum": [ "meeting", "upload" ], "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "maxLength": 200, "type": "string" } }, { "name": "q", "in": "query", "schema": { "maxLength": 500, "type": "string" } }, { "name": "page", "in": "query", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "schema": { "maximum": 1000, "minimum": 1, "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/bulk": { "post": { "tags": [ "Transcriptions" ], "summary": "Batch upload up to 50 single-track files (one transcription per file)", "description": "Multipart form with any number of file fields (name doesn't matter — every uploaded file becomes one transcription). Each file is queued as a system-only single-track upload, so stereo call-center recordings hit the per-speaker auto-detect path. Optional `language` applies to every file in the batch. Returns per-file success or reason for failure; a single file exceeding subscription limits does NOT fail the whole batch.", "operationId": "BulkCreateTranscriptions", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "language": { "type": "string" } } }, "encoding": { "language": { "style": "form" } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "language": { "type": "string" } } }, "encoding": { "language": { "style": "form" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionBulkUploadDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}": { "get": { "tags": [ "Transcriptions" ], "summary": "Get one transcription with current status/progress", "operationId": "GetTranscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "delete": { "tags": [ "Transcriptions" ], "summary": "Delete a transcription (soft delete)", "operationId": "DeleteTranscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}/segments": { "get": { "tags": [ "Transcriptions" ], "summary": "Get transcript segments ordered by start time", "operationId": "GetTranscriptionSegments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionSegmentListDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}/markdown": { "get": { "tags": [ "Transcriptions" ], "summary": "Get the transcript as markdown with timecodes and speaker tags", "operationId": "GetTranscriptionMarkdown", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}/audio/{track}": { "get": { "tags": [ "Transcriptions" ], "summary": "Download an original audio track (mic or system)", "operationId": "GetTranscriptionAudio", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "track", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}/events": { "get": { "tags": [ "Transcriptions" ], "summary": "Server-sent events with live processing progress", "description": "Starts with a snapshot 'status' event, then streams 'progress'/'status' events until the transcription reaches a terminal state. Safe to reconnect at any moment.", "operationId": "StreamTranscriptionEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/transcriptions/{id}/diarize": { "post": { "tags": [ "Transcriptions" ], "summary": "Queue speaker diarization on a completed transcription", "description": "Owner-only. Creates a Diarization ProcessingJob targeting this transcription; an agent with can_diarize picks it up and back-fills SpeakerLabel on existing segments.", "operationId": "RequestDiarization", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted" }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/me": { "get": { "tags": [ "User" ], "summary": "Get the currently authenticated user", "operationId": "GetCurrentUser", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "patch": { "tags": [ "User" ], "summary": "Edit the current user's profile (public username shown on leaderboards)", "operationId": "UpdateCurrentUser", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCurrentUser" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/version": { "get": { "tags": [ "Version" ], "summary": "Build/deployment metadata of the running backend", "operationId": "GetVersion", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionDto" } } } } } } }, "/v1/voice-prints": { "post": { "tags": [ "VoicePrints" ], "summary": "Register a new speaker embedding (pre-computed)", "description": "Body accepts a pre-computed pyannote embedding as a JSON array of doubles. For a WAV upload flow use POST /voice-prints/upload instead.", "operationId": "CreateVoicePrint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVoicePrint" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePrintDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "get": { "tags": [ "VoicePrints" ], "summary": "List my voice prints (owner-scoped)", "operationId": "ListVoicePrints", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePrintListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/voice-prints/upload": { "post": { "tags": [ "VoicePrints" ], "summary": "Upload an audio sample; a diarization-capable agent computes the embedding", "description": "Multipart form: audio (file, 5-30s recommended), label (string), subject_user_id (guid, optional). Returns immediately with Status=Pending — poll GET /voice-prints/{id} until Status=Ready (or Failed). An agent with can_diarize picks up the queued job and POSTs the embedding back.", "operationId": "UploadVoicePrint", "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "audio", "label" ], "type": "object", "properties": { "audio": { "type": "string", "format": "binary" }, "label": { "type": "string" }, "subject_user_id": { "type": "string", "format": "uuid" } } }, "encoding": { "audio": { "style": "form" }, "label": { "style": "form" }, "subject_user_id": { "style": "form" } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePrintDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/voice-prints/{id}": { "get": { "tags": [ "VoicePrints" ], "summary": "Get one voice print (poll for extraction status)", "operationId": "GetVoicePrint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePrintDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "put": { "tags": [ "VoicePrints" ], "summary": "Update label or subject user of a voice print", "operationId": "UpdateVoicePrint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVoicePrint" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoicePrintDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "delete": { "tags": [ "VoicePrints" ], "summary": "Delete a voice print (soft delete)", "operationId": "DeleteVoicePrint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint for the current account", "description": "Body: url (https), events (any of transcription.completed, transcription.failed, summary.completed, summary.failed), optional description. The signing `secret` is returned ONCE; every delivery carries `X-Wavesift-Signature: v1=.\">`. Up to 10 endpoints per account.", "operationId": "CreateWebhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhook" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreatedDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "get": { "tags": [ "Webhooks" ], "summary": "List the current account's webhook endpoints, newest first", "operationId": "ListWebhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/webhooks/{id}": { "put": { "tags": [ "Webhooks" ], "summary": "Change url, events, description or active flag of a webhook endpoint", "operationId": "UpdateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhook" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDto" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint; pending deliveries are dropped", "operationId": "DeleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Issue a new signing secret (the old one stops working immediately)", "operationId": "RotateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreatedDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Queue a `ping` delivery to verify the endpoint and signature handling", "operationId": "SendTestWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } }, "/v1/user/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Last 50 deliveries of an endpoint with status, attempts and last error", "operationId": "ListWebhookDeliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListDto" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKey": [ ] }, { "Bearer": [ ] } ] } } }, "components": { "schemas": { "ClientApiKeyDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ownerUserId": { "type": "string", "format": "uuid", "nullable": true }, "ownerEmail": { "type": "string", "nullable": true }, "partnerName": { "type": "string", "nullable": true }, "keyPrefix": { "type": "string", "nullable": true }, "bypassLimits": { "type": "boolean" }, "isActive": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ClientApiKeyIssuedDto": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ClientApiKeyDto" }, "apiKey": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ClientApiKeyListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClientApiKeyDto" }, "nullable": true } }, "additionalProperties": false }, "CreateApiKey": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "CreateSummaryPreset": { "required": [ "name", "prompt" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "prompt": { "minLength": 1, "type": "string" } }, "additionalProperties": false }, "CreateVoicePrint": { "required": [ "embedding", "embeddingModel", "label" ], "type": "object", "properties": { "label": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectUserId": { "type": "string", "format": "uuid", "nullable": true }, "embedding": { "type": "array", "items": { "type": "number", "format": "double" } }, "embeddingModel": { "maxLength": 100, "minLength": 1, "type": "string" } }, "additionalProperties": false }, "CreateWebhook": { "required": [ "events", "url" ], "type": "object", "properties": { "url": { "maxLength": 2048, "minLength": 1, "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "maxLength": 200, "type": "string", "nullable": true } }, "additionalProperties": false }, "GenerateSummary": { "required": [ "presetId" ], "type": "object", "properties": { "presetId": { "type": "string", "format": "uuid" } }, "additionalProperties": false }, "HealthDto": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "serverTime": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Login": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" } }, "additionalProperties": false }, "LoginResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/UserDto" } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": false }, "RefreshResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/UserDto" } }, "additionalProperties": false }, "Register": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "minLength": 1, "type": "string" }, "password": { "minLength": 1, "type": "string" }, "username": { "maxLength": 200, "type": "string", "nullable": true } }, "additionalProperties": false }, "RegisterResponse": { "type": "object", "properties": { "accessToken": { "type": "string", "nullable": true }, "user": { "$ref": "#/components/schemas/UserDto" } }, "additionalProperties": false }, "SubscriptionPlanDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "isEnabled": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "priceMonthly": { "type": "number", "format": "double" }, "currency": { "type": "string", "nullable": true }, "monthlyAudioMinutes": { "type": "integer", "format": "int32" }, "maxCustomPresets": { "type": "integer", "format": "int32" }, "maxUploadFileSizeMb": { "type": "integer", "format": "int32" }, "maxSeats": { "type": "integer", "format": "int32" }, "preferredSummaryModel": { "type": "string", "nullable": true }, "preferredWhisperModel": { "type": "string", "nullable": true }, "sortOrder": { "type": "integer", "format": "int32" }, "isTrial": { "type": "boolean" }, "trialDays": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "SubscriptionPlanListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlanDto" }, "nullable": true } }, "additionalProperties": false }, "SubscriptionStatus": { "enum": [ "active", "expired", "cancelled" ], "type": "string" }, "SubscriptionUsageDto": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time", "nullable": true }, "plan": { "$ref": "#/components/schemas/SubscriptionPlanDto" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "audioMinutesUsed": { "type": "number", "format": "double" }, "audioMinutesRemaining": { "type": "number", "format": "double", "nullable": true }, "transcriptionsCount": { "type": "integer", "format": "int32" }, "summariesCount": { "type": "integer", "format": "int32" }, "customPresetsCount": { "type": "integer", "format": "int32" }, "customPresetsRemaining": { "type": "integer", "format": "int32", "nullable": true } }, "additionalProperties": false }, "SummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "transcriptionId": { "type": "string", "format": "uuid" }, "presetId": { "type": "string", "format": "uuid", "nullable": true }, "presetName": { "type": "string", "nullable": true }, "ollamaModel": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/SummaryStatus" }, "markdown": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "SummaryListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryDto" }, "nullable": true } }, "additionalProperties": false }, "SummaryPresetDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "prompt": { "type": "string", "nullable": true }, "isGlobal": { "type": "boolean" }, "isEnabled": { "type": "boolean" }, "sortOrder": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "SummaryPresetListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryPresetDto" }, "nullable": true } }, "additionalProperties": false }, "SummaryStatus": { "enum": [ "queued", "processing", "completed", "failed" ], "type": "string" }, "TranscriptSource": { "enum": [ "you", "other" ], "type": "string" }, "TranscriptionBulkItemDto": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "fileName": { "type": "string", "nullable": true }, "transcription": { "$ref": "#/components/schemas/TranscriptionDto" }, "error": { "type": "string", "nullable": true } }, "additionalProperties": false }, "TranscriptionBulkUploadDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionBulkItemDto" }, "nullable": true } }, "additionalProperties": false }, "TranscriptionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/TranscriptionKind" }, "status": { "$ref": "#/components/schemas/TranscriptionStatus" }, "title": { "type": "string", "nullable": true }, "externalId": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "detectedLanguage": { "type": "string", "nullable": true }, "whisperModel": { "type": "string", "nullable": true }, "durationSeconds": { "type": "number", "format": "double", "nullable": true }, "hasMicTrack": { "type": "boolean" }, "hasSystemTrack": { "type": "boolean" }, "micFileSizeBytes": { "type": "integer", "format": "int64", "nullable": true }, "systemFileSizeBytes": { "type": "integer", "format": "int64", "nullable": true }, "progressStage": { "type": "string", "nullable": true }, "progressPercent": { "type": "integer", "format": "int32", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "audioDeletedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "TranscriptionKind": { "enum": [ "meeting", "upload" ], "type": "string" }, "TranscriptionListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionDto" }, "nullable": true }, "totalCount": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "TranscriptionSegmentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "start": { "type": "number", "format": "double" }, "end": { "type": "number", "format": "double" }, "text": { "type": "string", "nullable": true }, "source": { "$ref": "#/components/schemas/TranscriptSource" }, "speakerUserId": { "type": "string", "format": "uuid", "nullable": true }, "speakerLabel": { "type": "string", "nullable": true } }, "additionalProperties": false }, "TranscriptionSegmentListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionSegmentDto" }, "nullable": true } }, "additionalProperties": false }, "TranscriptionStatus": { "enum": [ "queued", "processing", "completed", "failed" ], "type": "string" }, "UpdateCurrentUser": { "type": "object", "properties": { "username": { "maxLength": 200, "type": "string", "nullable": true } }, "additionalProperties": false }, "UpdateSummaryPreset": { "required": [ "name", "prompt" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "prompt": { "minLength": 1, "type": "string" } }, "additionalProperties": false }, "UpdateVoicePrint": { "required": [ "label" ], "type": "object", "properties": { "label": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectUserId": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false }, "UpdateWebhook": { "required": [ "events", "url" ], "type": "object", "properties": { "url": { "maxLength": 2048, "minLength": 1, "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "maxLength": 200, "type": "string", "nullable": true }, "isActive": { "type": "boolean" } }, "additionalProperties": false }, "UserDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true }, "role": { "$ref": "#/components/schemas/UserRole" }, "status": { "$ref": "#/components/schemas/UserStatus" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "UserRole": { "enum": [ "admin", "client" ], "type": "string" }, "UserStatus": { "enum": [ "active", "inactive", "blocked" ], "type": "string" }, "VersionDto": { "type": "object", "properties": { "buildTime": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "nullable": true }, "uptime": { "type": "string", "nullable": true }, "host": { "type": "string", "nullable": true }, "assemblyVersion": { "type": "string", "nullable": true } }, "additionalProperties": false }, "VoicePrintDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/VoicePrintStatus" }, "label": { "type": "string", "nullable": true }, "subjectUserId": { "type": "string", "format": "uuid", "nullable": true }, "dimension": { "type": "integer", "format": "int32" }, "embeddingModel": { "type": "string", "nullable": true }, "sampleAudioPath": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "VoicePrintListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VoicePrintDto" }, "nullable": true } }, "additionalProperties": false }, "VoicePrintStatus": { "enum": [ "pending", "ready", "failed" ], "type": "string" }, "WebhookDeliveryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempts": { "type": "integer", "format": "int32" }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "lastStatusCode": { "type": "integer", "format": "int32", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "WebhookDeliveryListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryDto" }, "nullable": true } }, "additionalProperties": false }, "WebhookDeliveryStatus": { "enum": [ "pending", "delivered", "failed" ], "type": "string" }, "WebhookEndpointCreatedDto": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpointDto" }, "secret": { "type": "string", "nullable": true } }, "additionalProperties": false }, "WebhookEndpointDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" }, "nullable": true }, "isActive": { "type": "boolean" }, "failureStreak": { "type": "integer", "format": "int32" }, "lastDeliveryAt": { "type": "string", "format": "date-time", "nullable": true }, "lastStatusCode": { "type": "integer", "format": "int32", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "WebhookEndpointListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointDto" }, "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "Bearer": { "type": "http", "description": "JWT Authorization header using the Bearer scheme. Enter your token below.", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKey": { "type": "apiKey", "description": "Client API key (atk_…) issued for your account. Sent as the X-Api-Key header.", "name": "X-Api-Key", "in": "header" } } }, "tags": [ { "name": "ApiKeys" }, { "name": "Auth" }, { "name": "Health" }, { "name": "Subscription" }, { "name": "Summaries" }, { "name": "SummaryPresets" }, { "name": "Transcriptions" }, { "name": "User" }, { "name": "Version" }, { "name": "VoicePrints" }, { "name": "Webhooks" } ] }