{ "openapi": "3.1.0", "info": { "title": "KolWrite Public API", "version": "v1", "description": "Public v1 surface of the KolWrite API for personal access tokens and automations. Authenticate with `Authorization: Bearer kol_...` (or `X-API-Key`). Each operation lists its required token scope under `x-required-scope`.\n\nGuides: [Quickstart](/quickstart.md) \u00b7 [Authentication & scopes](/authentication.md) \u00b7 [Errors & rate limits](/errors.md) \u00b7 [llms.txt](/llms.txt)" }, "servers": [ { "url": "https://api.kolwrite.com", "description": "Production" } ], "paths": { "/api/v1/account/app-experience": { "get": { "tags": [ "account" ], "summary": "Get KolWrite app experience preference", "operationId": "get_account_app_experience_route_api_v1_account_app_experience_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "account:read" }, "patch": { "tags": [ "account" ], "summary": "Update KolWrite app experience preference", "operationId": "update_account_app_experience_route_api_v1_account_app_experience_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAppExperienceUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "account:write" } }, "/api/v1/account/features": { "get": { "tags": [ "account" ], "summary": "Get effective features for the signed-in user", "operationId": "get_account_features_route_api_v1_account_features_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "account:read" } }, "/api/v1/account/features/{feature_key}": { "get": { "tags": [ "account" ], "summary": "Get one effective feature for the signed-in user", "operationId": "get_account_feature_route_api_v1_account_features__feature_key__get", "parameters": [ { "name": "feature_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Feature Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "account:read" } }, "/api/v1/ai/openai/audio/transcriptions": { "post": { "tags": [ "ai" ], "summary": "Transcribe audio with KolWrite AI", "description": "Fast audio transcription path for short AI-widget voice clips.\n\nThis deliberately bypasses the durable transcription pipeline: no job row,\nno Temporal workflow, no VAD/chunk planner, no diarization/alignment, and no\nartifact fetch. The public contract mirrors OpenAI's\n`/audio/transcriptions` enough for our KolWrite provider client to call it,\nwhile the backend performs one direct Gemini `generate_content` request.\n\nSilence and steady noise in PCM WAV uploads are answered without a model\ncall or charge (empty `text`, `noSpeech` evidence, `speech_guard`). With\n`target_language`, `text` is the translation and `source_text` carries the\nsource-language words from the same single request.\n\n`model` is a managed alias (`kw-fast`, ...) or any transcription model id\nfrom `GET /api/v1/models` that has a cloud `live` route (`oracle-mini`,\n`oracle`, `oracle-pro`, `oracle-max`, `base-whisper`, ...). Every chunk is\ncharged for the provider tokens it used at the managed-AI rate; models\nwhose live route runs on the user's device answer\n`400 live_runs_on_device` with their `cloud_fallback`.\n\nWith `purpose=live` the response also carries `source_text` (the spoken\nwords), `language` (detected source language), `billing`\n{credits_charged, model, seconds, basis, pending} and, with `want_words`,\n`words` and `words_estimated`.", "operationId": "audio_transcriptions_api_v1_ai_openai_audio_transcriptions_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_audio_transcriptions_api_v1_ai_openai_audio_transcriptions_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "ai:use" } }, "/api/v1/ai/openai/chat/completions": { "post": { "tags": [ "ai" ], "summary": "Create a KolWrite AI chat completion", "description": "Proxy an OpenAI-compatible chat completion request.", "operationId": "chat_completions_api_v1_ai_openai_chat_completions_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "ai:use" } }, "/api/v1/ai/openai/embeddings": { "post": { "tags": [ "ai" ], "summary": "Create KolWrite AI embeddings", "description": "Create OpenAI-compatible embeddings through the managed index route.", "operationId": "embeddings_api_v1_ai_openai_embeddings_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "ai:use" } }, "/api/v1/ai/openai/images/generations": { "post": { "tags": [ "ai" ], "summary": "Generate an image with KolWrite AI", "description": "Generate Nano Banana images behind an OpenAI-compatible contract.", "operationId": "image_generations_api_v1_ai_openai_images_generations_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "ai:use" } }, "/api/v1/ai/openai/models": { "get": { "tags": [ "ai" ], "summary": "List KolWrite AI models", "description": "Return the stable public model aliases exposed to the app.", "operationId": "list_models_api_v1_ai_openai_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "ai:use" } }, "/api/v1/ai/openai/responses": { "post": { "tags": [ "ai" ], "summary": "Create a KolWrite AI response", "description": "Proxy an OpenAI Responses API request.", "operationId": "responses_api_v1_ai_openai_responses_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "ai:use" } }, "/api/v1/artifacts": { "get": { "tags": [ "artifacts" ], "summary": "List artifacts", "description": "List versioned artifacts owned by the current user.", "operationId": "list_artifacts_api_v1_artifacts_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "media_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, { "name": "artifact_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Type" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/artifacts/versions/{version_id}": { "get": { "tags": [ "artifacts" ], "summary": "Get artifact version by id", "description": "Fetch one immutable artifact version by version id.", "operationId": "get_artifact_version_by_id_api_v1_artifacts_versions__version_id__get", "parameters": [ { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "include_payload", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Payload" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/artifacts/{artifact_id}": { "get": { "tags": [ "artifacts" ], "summary": "Get artifact", "description": "Fetch one logical artifact and its current version pointer.", "operationId": "get_artifact_api_v1_artifacts__artifact_id__get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/artifacts/{artifact_id}/versions": { "get": { "tags": [ "artifacts" ], "summary": "List artifact versions", "description": "List immutable versions for an artifact.", "operationId": "list_artifact_versions_api_v1_artifacts__artifact_id__versions_get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "include_payload", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Media exports only: include each version's JSON payload, or null where it cannot be read, so a history needs one request instead of one per version.", "default": false, "title": "Include Payload" }, "description": "Media exports only: include each version's JSON payload, or null where it cannot be read, so a history needs one request instead of one per version." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" }, "post": { "tags": [ "artifacts" ], "summary": "Create artifact version (user save)", "description": "Create a new immutable artifact version from client-authored content. Used by the editor's save-as-new-version action. Flips current_version_id to the new version and inserts a matching PsTranscription row so the client's version history picks it up.", "operationId": "create_artifact_version_api_v1_artifacts__artifact_id__versions_post", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateArtifactVersionBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:write" } }, "/api/v1/artifacts/{artifact_id}/versions/{version_id}": { "get": { "tags": [ "artifacts" ], "summary": "Get artifact version", "description": "Fetch one immutable version and its canonical JSON payload.", "operationId": "get_artifact_version_api_v1_artifacts__artifact_id__versions__version_id__get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "include_payload", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Payload" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/artifacts/{artifact_id}/versions/{version_id}/download-url": { "get": { "tags": [ "artifacts" ], "summary": "Get artifact media download URL", "description": "Issue a short-lived signed URL for a media-export artifact output.", "operationId": "get_artifact_version_download_url_api_v1_artifacts__artifact_id__versions__version_id__download_url_get", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } }, { "name": "ttl_seconds", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 86400, "minimum": 60, "default": 3600, "title": "Ttl Seconds" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/artifacts/{artifact_id}/versions/{version_id}/restore": { "post": { "tags": [ "artifacts" ], "summary": "Restore artifact version as current", "description": "Promote one immutable artifact version to be the current version.", "operationId": "restore_artifact_version_api_v1_artifacts__artifact_id__versions__version_id__restore_post", "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact Id" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Version Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:write" } }, "/api/v1/auth/devices": { "get": { "tags": [ "auth" ], "summary": "List Device Sessions Route", "operationId": "list_device_sessions_route_api_v1_auth_devices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response List Device Sessions Route Api V1 Auth Devices Get" } } } } }, "x-required-scope": "devices:read" } }, "/api/v1/auth/devices/logout-all": { "post": { "tags": [ "auth" ], "summary": "Revoke All Device Sessions Route", "operationId": "revoke_all_device_sessions_route_api_v1_auth_devices_logout_all_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAllDeviceSessionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Revoke All Device Sessions Route Api V1 Auth Devices Logout All Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "devices:write" } }, "/api/v1/auth/devices/{device_id}/logout": { "post": { "tags": [ "auth" ], "summary": "Revoke Device Session Route", "operationId": "revoke_device_session_route_api_v1_auth_devices__device_id__logout_post", "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Device Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDeviceSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Revoke Device Session Route Api V1 Auth Devices Device Id Logout Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "devices:write" } }, "/api/v1/billing/balance": { "get": { "tags": [ "billing" ], "summary": "Get billing balance", "operationId": "get_billing_balance_route_api_v1_billing_balance_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "billing:read" } }, "/api/v1/billing/grants": { "get": { "tags": [ "billing" ], "summary": "List credit grants", "operationId": "list_grants_route_api_v1_billing_grants_get", "parameters": [ { "name": "include_expired", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Expired" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "billing:read" } }, "/api/v1/billing/ledger": { "get": { "tags": [ "billing" ], "summary": "Get billing ledger", "operationId": "get_billing_ledger_route_api_v1_billing_ledger_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "billing:read" } }, "/api/v1/billing/principal-balances": { "get": { "tags": [ "billing" ], "summary": "List visible principal billing balances", "operationId": "list_principal_billing_balances_route_api_v1_billing_principal_balances_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "billing:read" } }, "/api/v1/billing/profile": { "get": { "tags": [ "billing" ], "summary": "Get billing profile", "operationId": "get_billing_profile_route_api_v1_billing_profile_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "billing:read" } }, "/api/v1/cloud-storage/usage": { "get": { "tags": [ "cloud-storage" ], "summary": "Get cloud storage usage", "operationId": "get_cloud_storage_usage_route_api_v1_cloud_storage_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-required-scope": "files:read" } }, "/api/v1/format": { "post": { "tags": [ "format" ], "summary": "Format transcript", "description": "Convert canonical transcript JSON into the requested output format. Stateless, pure transform \u2014 no authentication required.", "operationId": "format_endpoint_api_v1_format_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/jobs": { "get": { "tags": [ "jobs" ], "summary": "List jobs", "description": "List jobs for the current user.", "operationId": "list_jobs_api_v1_jobs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" }, "post": { "tags": [ "jobs" ], "summary": "Create a job", "description": "Create a durable asynchronous job. v1 supports backend transcription jobs and client-local jobs for profiles that opt into execution_mode='client_local'.", "operationId": "create_job_api_v1_jobs_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:write" } }, "/api/v1/jobs/queue": { "get": { "tags": [ "jobs" ], "summary": "List active job queue", "description": "List running and queued jobs with queue totals for the current user.", "operationId": "get_job_queue_api_v1_jobs_queue_get", "parameters": [ { "name": "job_type", "in": "query", "required": false, "schema": { "type": "string", "default": "transcription", "title": "Job Type" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" } }, "/api/v1/jobs/queue/reorder": { "post": { "tags": [ "jobs" ], "summary": "Reorder a queued job", "description": "Move one queued job before another queued job, or to the queue end.", "operationId": "reorder_job_queue_api_v1_jobs_queue_reorder_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderJobQueueRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:write" } }, "/api/v1/jobs/{job_id}": { "get": { "tags": [ "jobs" ], "summary": "Get job status", "description": "Poll the status and progress of a processing job.", "operationId": "get_job_api_v1_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" }, "delete": { "tags": [ "jobs" ], "summary": "Cancel a job", "description": "Cancel a running processing job.", "operationId": "cancel_job_api_v1_jobs__job_id__delete", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:write" } }, "/api/v1/jobs/{job_id}/artifacts": { "get": { "tags": [ "jobs" ], "summary": "List job artifacts", "description": "List artifacts produced directly by this job.", "operationId": "list_job_artifacts_api_v1_jobs__job_id__artifacts_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" } }, "/api/v1/jobs/{job_id}/export": { "get": { "tags": [ "jobs" ], "summary": "Export job transcript", "description": "Export a completed job's transcript in the requested format. Supported formats: text, json, srt, vtt.", "operationId": "export_job_api_v1_jobs__job_id__export_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "description": "Output format: text, json, srt, vtt", "default": "json", "title": "Format" }, "description": "Output format: text, json, srt, vtt" }, { "name": "include_speakers", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include speaker labels (text/srt)", "default": true, "title": "Include Speakers" }, "description": "Include speaker labels (text/srt)" }, { "name": "include_timestamps", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include timestamps (text)", "default": false, "title": "Include Timestamps" }, "description": "Include timestamps (text)" }, { "name": "include_word_timestamps", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include word-level timestamps (json)", "default": true, "title": "Include Word Timestamps" }, "description": "Include word-level timestamps (json)" }, { "name": "pretty", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Pretty-print output (json)", "default": true, "title": "Pretty" }, "description": "Pretty-print output (json)" }, { "name": "max_chars_per_entry", "in": "query", "required": false, "schema": { "type": "integer", "description": "Max chars per subtitle entry (srt)", "default": 80, "title": "Max Chars Per Entry" }, "description": "Max chars per subtitle entry (srt)" }, { "name": "highlight_words", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Word-level karaoke highlighting (srt)", "default": false, "title": "Highlight Words" }, "description": "Word-level karaoke highlighting (srt)" }, { "name": "highlight_color", "in": "query", "required": false, "schema": { "type": "string", "description": "Highlight color for karaoke mode (srt)", "default": "yellow", "title": "Highlight Color" }, "description": "Highlight color for karaoke mode (srt)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" } }, "/api/v1/jobs/{job_id}/items": { "get": { "tags": [ "jobs" ], "summary": "List job items", "description": "List child items for a parent batch job.", "operationId": "list_job_items_api_v1_jobs__job_id__items_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "jobs:read" } }, "/api/v1/media": { "get": { "tags": [ "media" ], "summary": "List media", "description": "List the current user's media assets.", "operationId": "list_media_api_v1_media_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/media/complete": { "post": { "tags": [ "media" ], "summary": "Complete direct media upload", "description": "Verify and register a directly uploaded media object.", "operationId": "complete_media_upload_api_v1_media_complete_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteMediaUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "202": { "description": "Verification accepted. The data object contains status=verification_pending, verification_id, and retry_after_seconds. Poll with the same finalize token; acceptance is not completed cloud backup." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/media/register": { "post": { "tags": [ "media" ], "summary": "Register media from storage", "description": "Register an existing storage object as a reusable media asset.", "operationId": "register_media_api_v1_media_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterMediaRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/media/upload": { "post": { "tags": [ "media" ], "summary": "Upload media", "description": "Upload a media file and register it as a reusable media asset.", "operationId": "upload_media_api_v1_media_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_media_api_v1_media_upload_post" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/media/upload-session": { "post": { "tags": [ "media" ], "summary": "Create media upload session", "description": "Issue a short-lived signed URL for direct media upload.", "operationId": "create_media_upload_session_api_v1_media_upload_session_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User-Agent" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMediaUploadSessionRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/media/{media_id}": { "get": { "tags": [ "media" ], "summary": "Get media", "description": "Fetch a single media asset by id.", "operationId": "get_media_api_v1_media__media_id__get", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Media Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "delete": { "tags": [ "media" ], "summary": "Delete media", "description": "Delete a media asset and its S3 storage object.", "operationId": "delete_media_api_v1_media__media_id__delete", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Media Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/media/{media_id}/artifacts": { "get": { "tags": [ "media" ], "summary": "List media artifacts", "description": "List durable artifacts linked to a media asset.", "operationId": "list_media_artifacts_api_v1_media__media_id__artifacts_get", "parameters": [ { "name": "media_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Media Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "transcripts:read" } }, "/api/v1/models": { "get": { "tags": [ "models" ], "summary": "List available models", "description": "Returns the available transcription pipeline profiles (model codenames). Each profile defines a complete processing pipeline configuration. Use the codename in POST /api/v1/process to select a pipeline. Public profiles are always listed; internal profiles are listed only for users granted the matching feature.", "operationId": "get_models_api_v1_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/shares": { "get": { "tags": [ "public-sharing" ], "summary": "List shares", "description": "List shares created by the current user.", "operationId": "list_shares_route_api_v1_shares_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "target_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Id" } }, { "name": "target_version_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Version Id" } }, { "name": "share_kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Share Kind" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "default": "kolwrite", "title": "Product" } }, { "name": "release_channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(internal|alpha|beta|rc|stable)$" }, { "type": "null" } ], "title": "Release Channel" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:read" }, "post": { "tags": [ "public-sharing" ], "summary": "Create share", "description": "Create an authenticated transcript share link.", "operationId": "create_share_route_api_v1_shares_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareBody" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:write" } }, "/api/v1/shares/{share_id}": { "get": { "tags": [ "public-sharing" ], "summary": "Get share", "description": "Fetch share settings for management.", "operationId": "get_share_route_api_v1_shares__share_id__get", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "default": "kolwrite", "title": "Product" } }, { "name": "release_channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(internal|alpha|beta|rc|stable)$" }, { "type": "null" } ], "title": "Release Channel" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:read" }, "patch": { "tags": [ "public-sharing" ], "summary": "Update share", "description": "Update mutable share settings.", "operationId": "update_share_route_api_v1_shares__share_id__patch", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShareBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:write" }, "delete": { "tags": [ "public-sharing" ], "summary": "Disable share", "description": "Soft-delete/disable a share.", "operationId": "delete_share_route_api_v1_shares__share_id__delete", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:write" } }, "/api/v1/shares/{share_id}/revoke": { "post": { "tags": [ "public-sharing" ], "summary": "Revoke share", "description": "Revoke a share immediately.", "operationId": "revoke_share_route_api_v1_shares__share_id__revoke_post", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:write" } }, "/api/v1/shares/{share_id}/rotate": { "post": { "tags": [ "public-sharing" ], "summary": "Rotate share", "description": "Rotate the public URL slug. The new URL is returned once.", "operationId": "rotate_share_route_api_v1_shares__share_id__rotate_post", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Share Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RotateShareBody" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "shares:write" } }, "/api/v1/uploads": { "get": { "tags": [ "uploads" ], "summary": "List uploads", "description": "List uploads for the current user.", "operationId": "list_uploads_api_v1_uploads_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "post": { "tags": [ "uploads" ], "summary": "Create upload", "description": "Upload a file and receive an upload resource for later job creation.", "operationId": "upload_file_api_v1_uploads_post", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_file_api_v1_uploads_post" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/uploads/complete": { "post": { "tags": [ "uploads" ], "summary": "Complete direct upload", "description": "Verify and finalize a directly uploaded generic upload_ref object.", "operationId": "complete_upload_api_v1_uploads_complete_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/uploads/content": { "get": { "tags": [ "uploads" ], "summary": "Download upload content", "description": "Proxy a completed generic upload through the API.", "operationId": "download_upload_content_api_v1_uploads_content_get", "parameters": [ { "name": "storage_uri", "in": "query", "required": true, "schema": { "type": "string", "title": "Storage Uri" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/uploads/download-url": { "get": { "tags": [ "uploads" ], "summary": "Get upload download URL", "description": "Issue a short-lived signed URL for a completed generic upload.", "operationId": "get_upload_download_url_api_v1_uploads_download_url_get", "parameters": [ { "name": "storage_uri", "in": "query", "required": true, "schema": { "type": "string", "title": "Storage Uri" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/uploads/upload-session": { "post": { "tags": [ "uploads" ], "summary": "Create upload session", "description": "Issue a short-lived signed URL for direct generic upload.", "operationId": "create_upload_session_api_v1_uploads_upload_session_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadSessionRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/uploads/{upload_id}": { "get": { "tags": [ "uploads" ], "summary": "Get upload", "description": "Fetch a single upload resource by id.", "operationId": "get_upload_api_v1_uploads__upload_id__get", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/uploads/{upload_id}/cancel": { "post": { "tags": [ "uploads" ], "summary": "Cancel Upload Transfer", "operationId": "cancel_upload_transfer_api_v1_uploads__upload_id__cancel_post", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/uploads/{upload_id}/renew": { "post": { "tags": [ "uploads" ], "summary": "Renew Upload Transfer", "operationId": "renew_upload_transfer_api_v1_uploads__upload_id__renew_post", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewUploadTransferRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/uploads/{upload_id}/transfer": { "get": { "tags": [ "uploads" ], "summary": "Get Upload Transfer", "operationId": "get_upload_transfer_api_v1_uploads__upload_id__transfer_get", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Upload Id" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/workspace-files": { "get": { "tags": [ "workspaces" ], "summary": "List workspace files", "operationId": "list_workspace_files_route_api_v1_workspace_files_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "post": { "tags": [ "workspaces" ], "summary": "Register workspace file", "operationId": "create_workspace_file_route_api_v1_workspace_files_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceFileRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/workspace-files/{workspace_file_id}": { "get": { "tags": [ "workspaces" ], "summary": "Get workspace file", "operationId": "get_workspace_file_route_api_v1_workspace_files__workspace_file_id__get", "parameters": [ { "name": "workspace_file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace File Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/workspace-files/{workspace_file_id}/content": { "get": { "tags": [ "workspaces" ], "summary": "Download workspace file content", "operationId": "download_workspace_file_content_route_api_v1_workspace_files__workspace_file_id__content_get", "parameters": [ { "name": "workspace_file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace File Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/workspace-files/{workspace_file_id}/download-url": { "get": { "tags": [ "workspaces" ], "summary": "Get signed download URL", "operationId": "get_workspace_file_download_url_route_api_v1_workspace_files__workspace_file_id__download_url_get", "parameters": [ { "name": "workspace_file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace File Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } }, "/api/v1/workspace-folders": { "get": { "tags": [ "workspaces" ], "summary": "List workspace folders", "operationId": "list_workspace_folders_route_api_v1_workspace_folders_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "post": { "tags": [ "workspaces" ], "summary": "Create workspace folder", "operationId": "create_workspace_folder_route_api_v1_workspace_folders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceFolderRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/workspace-folders/{folder_id}": { "get": { "tags": [ "workspaces" ], "summary": "Get workspace folder", "operationId": "get_workspace_folder_route_api_v1_workspace_folders__folder_id__get", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } }, { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "patch": { "tags": [ "workspaces" ], "summary": "Update workspace folder", "operationId": "update_workspace_folder_route_api_v1_workspace_folders__folder_id__patch", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Folder Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceFolderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/workspaces": { "get": { "tags": [ "workspaces" ], "summary": "List workspaces", "operationId": "list_workspaces_route_api_v1_workspaces_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" }, "post": { "tags": [ "workspaces" ], "summary": "Create workspace", "operationId": "create_workspace_route_api_v1_workspaces_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:write" } }, "/api/v1/workspaces/{workspace_id}": { "get": { "tags": [ "workspaces" ], "summary": "Get workspace", "operationId": "get_workspace_route_api_v1_workspaces__workspace_id__get", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-required-scope": "files:read" } } }, "components": { "schemas": { "AccountAppExperienceUpdateRequest": { "properties": { "preferred_app": { "anyOf": [ { "type": "string", "pattern": "^(ask_me|legacy|new)$" }, { "type": "null" } ], "title": "Preferred App" }, "last_selected_app": { "anyOf": [ { "type": "string", "pattern": "^(legacy|new)$" }, { "type": "null" } ], "title": "Last Selected App" }, "beta_invite_state": { "anyOf": [ { "type": "string", "pattern": "^(seen|accepted|dismissed)$" }, { "type": "null" } ], "title": "Beta Invite State" }, "surface": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Surface" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "title": "AccountAppExperienceUpdateRequest" }, "AlignmentOptions": { "properties": { "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" } }, "type": "object", "title": "AlignmentOptions", "description": "Optional per-job timestamp-alignment override.\n\n``None`` deliberately means \"use the profile default\" so existing\nprofiles retain their current behavior while profiles such as Oracle Mini\ncan make alignment an explicit opt-in." }, "Body_audio_transcriptions_api_v1_ai_openai_audio_transcriptions_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" }, "model": { "type": "string", "title": "Model", "default": "kw-fast" }, "language": { "type": "string", "title": "Language", "default": "auto" }, "target_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Language" }, "prompt": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Prompt" }, "punctuation_mode": { "type": "string", "title": "Punctuation Mode", "default": "regular" }, "emoji_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Emoji Enabled" }, "emoji": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Emoji" }, "purpose": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Purpose", "description": "`dictation` (default) or `live`. `live` is for meeting and live caption chunks: the server adds no product-name spelling hint, and the clip may start or end mid-word." }, "context_text": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Context Text", "description": "Optional: the end of the previous line of the same live recording (the server keeps the last 200 characters). Used only for continuity; text that merely repeats it is withheld." }, "want_words": { "type": "boolean", "title": "Want Words", "description": "Return `words` [{w, start, end}] in seconds from the clip start. Engines without word timings estimate them inside the speech span and set `words_estimated`.", "default": false } }, "type": "object", "required": [ "file" ], "title": "Body_audio_transcriptions_api_v1_ai_openai_audio_transcriptions_post" }, "Body_upload_file_api_v1_uploads_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Audio/video file to upload" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_file_api_v1_uploads_post" }, "Body_upload_media_api_v1_media_upload_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File", "description": "Audio/video file to register as media" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "workspace_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace File Id" }, "source_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source File Id" }, "cloud_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cloud Path" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_media_api_v1_media_upload_post" }, "ChannelSpeakerSeparationOptions": { "properties": { "transcription": { "type": "string", "enum": [ "auto", "label_only", "independent" ], "title": "Transcription", "default": "auto" }, "trim_silence": { "type": "boolean", "title": "Trim Silence", "default": true }, "max_channels": { "anyOf": [ { "type": "integer", "maximum": 32.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Channels" }, "labels": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Labels" }, "fallback": { "type": "string", "enum": [ "regular", "pro", "none" ], "title": "Fallback", "default": "none" } }, "type": "object", "title": "ChannelSpeakerSeparationOptions", "description": "Channel-specific speaker separation options." }, "CompleteMediaUploadRequest": { "properties": { "finalize_token": { "type": "string", "maxLength": 8192, "minLength": 1, "title": "Finalize Token" }, "uploaded_parts": { "items": { "$ref": "#/components/schemas/CompletedUploadPart" }, "type": "array", "maxItems": 10000, "title": "Uploaded Parts" }, "verify_content": { "type": "boolean", "title": "Verify Content", "description": "Accept asynchronous verification: HTTP 202 returns verification_id and verification_pending; repeat completion with the same token until the normal media resource is returned. Accepted work remains status-readable after token expiry. False retains legacy completion.", "default": false } }, "type": "object", "required": [ "finalize_token" ], "title": "CompleteMediaUploadRequest", "description": "Complete a direct upload using a backend-issued finalize token." }, "CompleteUploadRequest": { "properties": { "finalize_token": { "type": "string", "maxLength": 8192, "minLength": 1, "title": "Finalize Token" }, "uploaded_parts": { "items": { "$ref": "#/components/schemas/CompletedUploadPart" }, "type": "array", "maxItems": 10000, "title": "Uploaded Parts" } }, "type": "object", "required": [ "finalize_token" ], "title": "CompleteUploadRequest", "description": "Complete a direct upload using a backend-issued finalize token." }, "CompletedUploadPart": { "properties": { "part_number": { "type": "integer", "maximum": 10000.0, "minimum": 1.0, "title": "Part Number" }, "etag": { "type": "string", "maxLength": 1024, "minLength": 1, "title": "Etag" } }, "type": "object", "required": [ "part_number", "etag" ], "title": "CompletedUploadPart", "description": "Completed multipart upload part." }, "CreateArtifactVersionBody": { "properties": { "payload": { "additionalProperties": true, "type": "object", "title": "Payload", "description": "Artifact-type-specific JSON blob" }, "parent_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Version Id" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "payload" ], "title": "CreateArtifactVersionBody", "description": "Client-authored artifact version. Used by the editor's save-as-new-version\nflow to snapshot the in-memory state as an immutable version.\n\n`payload` is an opaque JSON dict \u2014 server stores it verbatim in object\nstorage and never inspects it (schema is artifact-type-specific). For\ntranscripts the client sends `{segments, full_text, metadata}` matching\nthe job-pipeline output shape.\n\n`parent_version_id` is optional. When provided, the server records it on\nthe new row's `parent_version_id` column \u2014 the DAG pointer Phase 4e will\nwalk for fork detection. v1 accepts any parent (no optimistic-concurrency\nrejection yet).\n\n`label` is an optional user-supplied name; stored in the version's\n`metadata_json.label`." }, "CreateJobRequest": { "properties": { "type": { "type": "string", "enum": [ "transcription", "caption_burn", "render", "export" ], "title": "Type" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "billing_principal_type": { "anyOf": [ { "type": "string", "enum": [ "user", "team", "organization" ] }, { "type": "null" } ], "title": "Billing Principal Type" }, "billing_principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Principal Id" }, "input": { "$ref": "#/components/schemas/JobInput" }, "profile": { "type": "string", "title": "Profile", "default": "oracle" }, "options": { "$ref": "#/components/schemas/TranscriptionOptions" }, "file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Id" } }, "type": "object", "required": [ "type", "input" ], "title": "CreateJobRequest", "description": "Canonical public job creation request." }, "CreateMediaUploadSessionRequest": { "properties": { "filename": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Filename" }, "file_size_bytes": { "anyOf": [ { "type": "integer", "maximum": 5492189429760.0, "minimum": 0.0 }, { "type": "null" } ], "title": "File Size Bytes" }, "content_type": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Content Type" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "workspace_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace File Id" }, "source_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source File Id" }, "cloud_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cloud Path" }, "prefer_multipart": { "type": "boolean", "title": "Prefer Multipart", "default": false }, "content_sha256": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, { "type": "null" } ], "title": "Content Sha256" } }, "type": "object", "required": [ "filename" ], "title": "CreateMediaUploadSessionRequest", "description": "Request a short-lived direct upload session for media bytes." }, "CreateShareBody": { "properties": { "share_kind": { "type": "string", "title": "Share Kind", "default": "transcript" }, "artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Id" }, "artifact_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artifact Version Id" }, "app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Id" }, "app_version_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "App Version Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "permissions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Permissions" }, "presentation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Presentation" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "access_scope": { "type": "string", "pattern": "^(everyone|restricted|public|anyone|anyone_with_link|specific|private)$", "title": "Access Scope", "default": "everyone" }, "recipient_emails": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Recipient Emails" }, "recipient_uids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UidRecipient" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Recipient Uids" }, "notify_recipients": { "type": "boolean", "title": "Notify Recipients", "default": true }, "reshared_from_share_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Reshared From Share Id" }, "product": { "type": "string", "title": "Product", "default": "kolwrite" }, "release_channel": { "anyOf": [ { "type": "string", "pattern": "^(internal|alpha|beta|rc|stable)$" }, { "type": "null" } ], "title": "Release Channel" } }, "type": "object", "title": "CreateShareBody", "description": "Create a transcript or private installed-app share." }, "CreateUploadSessionRequest": { "properties": { "filename": { "type": "string", "maxLength": 512, "minLength": 1, "title": "Filename" }, "file_size_bytes": { "anyOf": [ { "type": "integer", "maximum": 5492189429760.0, "minimum": 0.0 }, { "type": "null" } ], "title": "File Size Bytes" }, "content_type": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Content Type" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "content_sha256": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 64 }, { "type": "null" } ], "title": "Content Sha256" }, "retention": { "anyOf": [ { "type": "string", "const": "job_input" }, { "type": "null" } ], "title": "Retention" } }, "type": "object", "required": [ "filename" ], "title": "CreateUploadSessionRequest", "description": "Request a short-lived direct upload session for generic uploaded bytes." }, "CreateWorkspaceFileRequest": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "workspace_id": { "type": "string", "title": "Workspace Id" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder Id" }, "filename": { "type": "string", "title": "Filename" }, "storage_uri": { "type": "string", "title": "Storage Uri" }, "logical_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logical Path" }, "cloud_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cloud Path" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type" }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checksum" }, "file_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Kind" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "workspace_id", "filename", "storage_uri" ], "title": "CreateWorkspaceFileRequest", "description": "Register a canonical synced file inside a workspace." }, "CreateWorkspaceFolderRequest": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "workspace_id": { "type": "string", "title": "Workspace Id" }, "name": { "type": "string", "title": "Name" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "workspace_id", "name" ], "title": "CreateWorkspaceFolderRequest", "description": "Create a canonical folder in a workspace." }, "CreateWorkspaceRequest": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "name": { "type": "string", "title": "Name" }, "workspace_type": { "type": "string", "title": "Workspace Type", "default": "cloud" }, "owner_principal_type": { "anyOf": [ { "type": "string", "pattern": "^(user|team|organization)$" }, { "type": "null" } ], "title": "Owner Principal Type" }, "owner_principal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Principal Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "name" ], "title": "CreateWorkspaceRequest", "description": "Create a canonical backend workspace." }, "DiarizationOptions": { "properties": { "mode": { "type": "string", "enum": [ "none", "regular", "pro", "channels", "channels-independent-asr" ], "title": "Mode", "default": "none" }, "num_speakers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Speakers" }, "auto_speaker_names": { "type": "boolean", "title": "Auto Speaker Names", "default": true } }, "type": "object", "title": "DiarizationOptions", "description": "Per-job diarization options." }, "FormatRequest": { "properties": { "transcript": { "additionalProperties": true, "type": "object", "title": "Transcript", "description": "Canonical transcript JSON (segments, full_text, metadata)" }, "format": { "type": "string", "title": "Format", "description": "Output format: text, json, srt, vtt" }, "options": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Options", "description": "Format-specific options" } }, "type": "object", "required": [ "transcript", "format" ], "title": "FormatRequest", "description": "Request body for the format endpoint.", "examples": [ { "format": "srt", "options": { "include_speakers": true }, "transcript": { "full_text": "Hello world", "metadata": { "total_segments": 1 }, "segments": [ { "end": 4.5, "speaker": "Alice", "start": 0.0, "text": "Hello world" } ] } } ] }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JobInput": { "properties": { "type": { "type": "string", "enum": [ "client_file_ref", "storage_uri", "media_ref", "upload_ref", "workspace_file_ref", "selection_ref", "folder_ref", "workspace_ref" ], "title": "Type" }, "uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Uri" }, "media_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Id" }, "upload_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Id" }, "client_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client File Id" }, "workspace_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace File Id" }, "workspace_file_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Workspace File Ids" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder Id" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" } }, "type": "object", "required": [ "type" ], "title": "JobInput", "description": "Typed job input descriptor." }, "RegisterMediaRequest": { "properties": { "storage_uri": { "type": "string", "title": "Storage Uri" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "workspace_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace File Id" }, "source_file_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source File Id" }, "cloud_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cloud Path" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "storage_uri" ], "title": "RegisterMediaRequest", "description": "Register an existing storage object as media." }, "RenewUploadTransferRequest": { "properties": { "part_numbers": { "anyOf": [ { "items": { "type": "integer", "maximum": 10000.0, "minimum": 1.0 }, "type": "array", "maxItems": 10000 }, { "type": "null" } ], "title": "Part Numbers" } }, "type": "object", "title": "RenewUploadTransferRequest" }, "ReorderJobQueueRequest": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "before_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Before Job Id" } }, "type": "object", "required": [ "job_id" ], "title": "ReorderJobQueueRequest" }, "ReuseTranscriptSegment": { "properties": { "start": { "type": "number", "minimum": 0.0, "title": "Start" }, "end": { "type": "number", "minimum": 0.0, "title": "End" }, "text": { "type": "string", "maxLength": 4000, "title": "Text" }, "language": { "anyOf": [ { "type": "string", "maxLength": 35 }, { "type": "null" } ], "title": "Language" } }, "type": "object", "required": [ "start", "end", "text" ], "title": "ReuseTranscriptSegment", "description": "One timed line of the transcript to keep (seconds from media start)." }, "RevokeAllDeviceSessionsRequest": { "properties": { "include_current_device": { "type": "boolean", "title": "Include Current Device", "default": false }, "forget_devices": { "type": "boolean", "title": "Forget Devices", "default": false }, "delete_local_storage": { "type": "boolean", "title": "Delete Local Storage", "default": false } }, "type": "object", "title": "RevokeAllDeviceSessionsRequest" }, "RevokeDeviceSessionRequest": { "properties": { "forget_device": { "type": "boolean", "title": "Forget Device", "default": false }, "delete_local_storage": { "type": "boolean", "title": "Delete Local Storage", "default": false } }, "type": "object", "title": "RevokeDeviceSessionRequest" }, "RotateShareBody": { "properties": { "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "product": { "type": "string", "title": "Product", "default": "kolwrite" }, "release_channel": { "anyOf": [ { "type": "string", "pattern": "^(internal|alpha|beta|rc|stable)$" }, { "type": "null" } ], "title": "Release Channel" } }, "type": "object", "title": "RotateShareBody", "description": "Rotate a share URL." }, "SpeakerBankCandidateOptions": { "properties": { "speaker_bank_id": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Speaker Bank Id" }, "display_name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Display Name" }, "aliases": { "items": { "type": "string", "maxLength": 120, "minLength": 1 }, "type": "array", "maxItems": 8, "title": "Aliases" }, "confidence": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "default": 0.0 }, "transcript_count": { "type": "integer", "maximum": 100000.0, "minimum": 0.0, "title": "Transcript Count", "default": 0 }, "total_segments": { "type": "integer", "maximum": 1000000.0, "minimum": 0.0, "title": "Total Segments", "default": 0 }, "total_duration_seconds": { "type": "number", "maximum": 31536000.0, "minimum": 0.0, "title": "Total Duration Seconds", "default": 0.0 }, "last_seen_at": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Last Seen At" }, "file_refs": { "items": { "$ref": "#/components/schemas/SpeakerBankFileRefOptions" }, "type": "array", "maxItems": 6, "title": "File Refs" } }, "type": "object", "required": [ "speaker_bank_id", "display_name" ], "title": "SpeakerBankCandidateOptions", "description": "One speaker-bank candidate supplied by the client." }, "SpeakerBankFileRefOptions": { "properties": { "file_id": { "type": "string", "maxLength": 128, "minLength": 1, "title": "File Id" }, "file_name": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ], "title": "File Name" }, "source_speaker_id": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Source Speaker Id" }, "segment_count": { "type": "integer", "maximum": 100000.0, "minimum": 0.0, "title": "Segment Count", "default": 0 }, "duration_seconds": { "type": "number", "maximum": 86400.0, "minimum": 0.0, "title": "Duration Seconds", "default": 0.0 }, "last_seen_at": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Last Seen At" }, "sample_windows": { "items": { "$ref": "#/components/schemas/SpeakerBankSampleWindowOptions" }, "type": "array", "maxItems": 4, "title": "Sample Windows" } }, "type": "object", "required": [ "file_id", "source_speaker_id" ], "title": "SpeakerBankFileRefOptions", "description": "Compact reference to a previous transcript speaker occurrence." }, "SpeakerBankOptions": { "properties": { "schema_version": { "type": "integer", "maximum": 1.0, "minimum": 1.0, "title": "Schema Version", "default": 1 }, "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "learn_automatically": { "type": "boolean", "title": "Learn Automatically", "default": true }, "suggest_when_recognition_off": { "type": "boolean", "title": "Suggest When Recognition Off", "default": true }, "sample_matching_enabled": { "type": "boolean", "title": "Sample Matching Enabled", "default": false }, "policy": { "$ref": "#/components/schemas/SpeakerBankPolicyOptions" }, "privacy": { "anyOf": [ { "$ref": "#/components/schemas/SpeakerBankPrivacyOptions" }, { "type": "null" } ] }, "candidates": { "items": { "$ref": "#/components/schemas/SpeakerBankCandidateOptions" }, "type": "array", "maxItems": 24, "title": "Candidates" } }, "type": "object", "title": "SpeakerBankOptions", "description": "Client-supplied speaker-bank recognition hints.\n\nThe payload intentionally contains compact profile metadata only. Photos and\nsaved audio samples are not accepted here. Workers use the names as\ndeterministic text hints only; acoustic matching is device-local." }, "SpeakerBankPolicyOptions": { "properties": { "max_sample_seconds_per_job": { "type": "integer", "maximum": 60.0, "minimum": 0.0, "title": "Max Sample Seconds Per Job", "default": 18 }, "max_speakers_per_match_run": { "type": "integer", "maximum": 24.0, "minimum": 1.0, "title": "Max Speakers Per Match Run", "default": 8 }, "min_confidence": { "type": "number", "maximum": 0.95, "minimum": 0.35, "title": "Min Confidence", "default": 0.58 }, "candidate_limit": { "type": "integer", "maximum": 24.0, "minimum": 1.0, "title": "Candidate Limit", "default": 8 }, "sample_strategy": { "type": "string", "maxLength": 80, "title": "Sample Strategy", "default": "short_high_confidence_slices" }, "max_sample_seconds_per_candidate": { "type": "integer", "maximum": 30.0, "minimum": 0.0, "title": "Max Sample Seconds Per Candidate", "default": 3 } }, "type": "object", "title": "SpeakerBankPolicyOptions", "description": "Cost and privacy caps for speaker-bank matching." }, "SpeakerBankPrivacyOptions": { "properties": { "transfers_photos": { "type": "boolean", "const": false, "title": "Transfers Photos", "default": false }, "transfers_saved_audio": { "type": "boolean", "const": false, "title": "Transfers Saved Audio", "default": false }, "server_should_extract_only_current_job_samples": { "type": "boolean", "title": "Server Should Extract Only Current Job Samples", "default": false } }, "type": "object", "title": "SpeakerBankPrivacyOptions", "description": "Hard privacy assertions accepted from speaker-bank clients.\n\nRaw photos and saved audio never belong in a job-options payload. Keeping\nthese fields typed as ``False`` prevents a future client from silently\nwidening the transfer contract through the old arbitrary dictionary." }, "SpeakerBankSampleWindowOptions": { "properties": { "start_seconds": { "type": "number", "maximum": 86400.0, "minimum": 0.0, "title": "Start Seconds" }, "end_seconds": { "type": "number", "maximum": 86400.0, "minimum": 0.0, "title": "End Seconds" }, "duration_seconds": { "type": "number", "maximum": 60.0, "minimum": 0.0, "title": "Duration Seconds", "default": 0.0 }, "text_preview": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ], "title": "Text Preview" } }, "type": "object", "required": [ "start_seconds", "end_seconds" ], "title": "SpeakerBankSampleWindowOptions", "description": "Timestamp range for a short speaker voice sample." }, "SpeakerSeparationOptions": { "properties": { "mode": { "type": "string", "enum": [ "none", "auto", "channels", "diarization" ], "title": "Mode", "default": "none" }, "quality": { "type": "string", "enum": [ "standard", "premium" ], "title": "Quality", "default": "standard" }, "channels": { "$ref": "#/components/schemas/ChannelSpeakerSeparationOptions" } }, "type": "object", "title": "SpeakerSeparationOptions", "description": "User-facing speaker separation settings.\n\nThis is intentionally product-oriented. Legacy `diarization` remains\naccepted and is mirrored into this shape by `TranscriptionOptions`." }, "TranscriptionOptions": { "properties": { "product_id": { "anyOf": [ { "type": "string", "enum": [ "kolhive", "kolwrite" ] }, { "type": "null" } ], "title": "Product Id" }, "language": { "type": "string", "title": "Language", "default": "auto" }, "target_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Language" }, "transcription_prompt": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Transcription Prompt" }, "diarization": { "$ref": "#/components/schemas/DiarizationOptions" }, "alignment": { "$ref": "#/components/schemas/AlignmentOptions" }, "speaker_separation": { "anyOf": [ { "$ref": "#/components/schemas/SpeakerSeparationOptions" }, { "type": "null" } ] }, "speaker_bank": { "anyOf": [ { "$ref": "#/components/schemas/SpeakerBankOptions" }, { "type": "null" } ] }, "caption_burn": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Caption Burn" }, "transcript_carryover": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Transcript Carryover" }, "notification_option": { "type": "string", "enum": [ "none", "each", "all" ], "title": "Notification Option", "default": "none" }, "email_summary_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email Summary Enabled" }, "completion_email": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Completion Email" }, "reuse_transcript_segments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ReuseTranscriptSegment" }, "type": "array", "maxItems": 20000 }, { "type": "null" } ], "title": "Reuse Transcript Segments", "description": "Speakers-only cleanup (profile `speakers-only`): the timed lines of an existing transcript, kept word for word. The job adds word timings and speakers only and is charged the diarization add-on." } }, "type": "object", "title": "TranscriptionOptions", "description": "Per-job transcription options." }, "UidRecipient": { "properties": { "uid": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Uid" }, "match_grant": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 16 }, { "type": "null" } ], "title": "Match Grant" } }, "additionalProperties": false, "type": "object", "required": [ "uid" ], "title": "UidRecipient" }, "UpdateShareBody": { "properties": { "artifact_version_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Artifact Version Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "permissions": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Permissions" }, "presentation": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Presentation" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "clear_expires_at": { "type": "boolean", "title": "Clear Expires At", "default": false }, "access_scope": { "anyOf": [ { "type": "string", "pattern": "^(everyone|restricted|public|anyone|anyone_with_link|specific|private)$" }, { "type": "null" } ], "title": "Access Scope" }, "recipient_emails": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Recipient Emails" }, "recipient_uids": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UidRecipient" }, "type": "array", "maxItems": 100 }, { "type": "null" } ], "title": "Recipient Uids" }, "notify_recipients": { "type": "boolean", "title": "Notify Recipients", "default": true }, "product": { "type": "string", "title": "Product", "default": "kolwrite" }, "release_channel": { "anyOf": [ { "type": "string", "pattern": "^(internal|alpha|beta|rc|stable)$" }, { "type": "null" } ], "title": "Release Channel" } }, "type": "object", "title": "UpdateShareBody", "description": "Mutable share settings." }, "UpdateWorkspaceFolderRequest": { "properties": { "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "title": "UpdateWorkspaceFolderRequest", "description": "Update or canonically merge a folder in a workspace." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication. The hardcoded dev-test-key works only in explicitly enabled local debug deployments." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Firebase JWT, or a personal access token (kol_...) subject to its granted scopes" } } }, "security": [ { "APIKeyHeader": [] }, { "BearerAuth": [] } ], "x-scopes": { "account:read": "Read profile feature flags and app experience preferences", "account:write": "Update app experience preferences", "ai:use": "Use KolWrite managed AI (chat, embeddings, fast transcription); spends credits", "billing:read": "Read credit balance, ledger, and grants", "devices:read": "List signed-in device sessions", "devices:write": "Log out device sessions", "files:read": "List and download files, folders, media, and uploads; read storage usage", "files:write": "Upload files, register media, and create or update folders and workspaces", "jobs:read": "Read job status, queue position, results, and job artifacts", "jobs:write": "Create and cancel processing jobs (transcription, caption burn) and reorder the queue", "shares:read": "List and inspect public share links", "shares:write": "Create, update, rotate, and revoke public share links", "transcripts:read": "Read transcripts, transcript versions, and export download URLs", "transcripts:write": "Save new transcript versions and restore previous versions" } }