{"openapi":"3.1.0","info":{"title":"Transkripce — Agent API","summary":"Czech audio/video transcription API for AI agents","description":"Versioned agent-facing API for the Transkripce product (transkripce.i-dotaznik.cz). Upload audio/video, start an automatic multi-provider transcription workflow (transcription -> merge -> quality check), poll status and download machine-readable results. Mutating endpoints support the `Idempotency-Key` header. Costs are charged in prepaid credits (1 credit per started minute of audio); calls without sufficient credits return HTTP 402 with a structured payload.","version":"1.0.0"},"paths":{"/keys":{"get":{"tags":["keys"],"summary":"List Keys","description":"List agent API keys of the authenticated user (no secrets).","operationId":"list_keys_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyListResponse"}}}}}},"post":{"tags":["keys"],"summary":"Create Key","description":"Create a new agent API key (full key is returned only once).","operationId":"create_key_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyCreatedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/keys/{key_id}":{"delete":{"tags":["keys"],"summary":"Revoke Key","description":"Revoke an agent API key (immediate kill-switch).","operationId":"revoke_key_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"tags":["meta"],"summary":"Api Info","description":"Identity and entry points of this API (machine-readable discovery).","operationId":"api_info__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApiInfo"}}}}}}},"/audio-files":{"get":{"tags":["audio-files"],"summary":"List Audio Files","description":"List uploaded audio files owned by the authenticated user.","operationId":"list_audio_files_audio_files_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response List Audio Files Audio Files Get"}}}}}},"post":{"tags":["audio-files"],"summary":"Upload Audio","description":"Upload an audio/video file; returns `file_id` used to start a workflow.\n\nRequires the `transcription:write` scope when called with an agent key.","operationId":"upload_audio_audio_files_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_audio_audio_files_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Upload Audio Audio Files Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflows":{"post":{"tags":["workflows"],"summary":"Create Workflow","description":"Start an automatic transcription workflow (transcription -> merge -> quality).\n\nSupports the `Idempotency-Key` header: repeated calls with the same key\nreplay the original response instead of starting a duplicate workflow.\nReturns 402 with a structured payload when credits are insufficient or\nthe agent key budget is exceeded (`AGENT_KEY_BUDGET_EXCEEDED`).\nRequires the `transcription:write` scope when called with an agent key.","operationId":"create_workflow_workflows_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionWorkflowCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionWorkflowCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["workflows"],"summary":"List Workflows","description":"List transcription workflows of the authenticated user (newest first).","operationId":"list_workflows_workflows_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"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":{"title":"Response List Workflows Workflows Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflows/{workflow_id}":{"get":{"tags":["workflows"],"summary":"Get Workflow","description":"Get one workflow by ID (status, job IDs, billing, error).","operationId":"get_workflow_workflows__workflow_id__get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Get Workflow Workflows  Workflow Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflows/{workflow_id}/transcript":{"get":{"tags":["workflows"],"summary":"Get Workflow Transcript","description":"Download the final merged transcript of a completed workflow.","operationId":"get_workflow_transcript_workflows__workflow_id__transcript_get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Export format: txt, json, md, docx","default":"txt","title":"Format"},"description":"Export format: txt, json, md, docx"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Get Workflow Transcript Workflows  Workflow Id  Transcript Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/workflows/{workflow_id}/quality-report":{"get":{"tags":["workflows"],"summary":"Get Workflow Quality Report","description":"Download the quality audit report of a completed workflow.","operationId":"get_workflow_quality_report_workflows__workflow_id__quality_report_get","parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Export format: txt, md, docx","default":"txt","title":"Format"},"description":"Export format: txt, md, docx"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Get Workflow Quality Report Workflows  Workflow Id  Quality Report Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credits/packages":{"get":{"tags":["credits"],"summary":"Credits Packages","description":"List purchasable credit packages (public price list, CZK).","operationId":"credits_packages_credits_packages_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Credits Packages Credits Packages Get"}}}}}}},"/credits/topup":{"post":{"tags":["credits"],"summary":"Credits Topup","description":"Create a Stripe Checkout payment link for a credit package.\n\nHuman-in-the-loop: the agent only PREPARES the payment link; the human\naccount owner must open `payment_url` and complete the payment. No\ncard or payment method is ever exposed to the agent. Requires the\n`transcription:write` scope when called with an agent key.","operationId":"credits_topup_credits_topup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionTopupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionTopupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/credits/pricing":{"get":{"tags":["credits"],"summary":"Credits Pricing","description":"Machine-readable price list of billable actions (stable action IDs).","operationId":"credits_pricing_credits_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Credits Pricing Credits Pricing Get"}}}}}}},"/credits/balance":{"get":{"tags":["credits"],"summary":"Credits Balance","description":"Current prepaid credit balance (total, reserved, available).","operationId":"credits_balance_credits_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Credits Balance Credits Balance Get"}}}}}}},"/credits/estimate":{"post":{"tags":["credits"],"summary":"Credits Estimate","description":"Estimate credit cost for a given audio duration in seconds.","operationId":"credits_estimate_credits_estimate_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Credits Estimate Credits Estimate Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentApiInfo":{"properties":{"name":{"type":"string","title":"Name","default":"transcription"},"title":{"type":"string","title":"Title","default":"Transkripce — Agent API"},"version":{"type":"string","title":"Version","default":"1.0.0"},"description":{"type":"string","title":"Description","default":"Czech audio/video transcription for AI agents: upload media, run an automatic multi-provider transcription workflow, download the final transcript and quality report."},"docs_url":{"type":"string","title":"Docs Url","default":"/api/v1/transcription/docs"},"openapi_url":{"type":"string","title":"Openapi Url","default":"/api/v1/transcription/openapi.json"}},"type":"object","title":"AgentApiInfo","description":"[CZ] Zakladni identita API pro discovery (GET /)."},"AgentKeyCreateRequest":{"properties":{"label":{"type":"string","maxLength":100,"minLength":1,"title":"Label","description":"Human-readable key label"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"Granted scopes; defaults to transcription:read + transcription:write"},"expires_in_days":{"anyOf":[{"type":"integer","maximum":3650.0,"minimum":1.0},{"type":"null"}],"title":"Expires In Days","description":"Optional expiry in days from now"},"budget_daily_credits":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Budget Daily Credits","description":"Daily spending cap in credits (None = unlimited)"},"budget_monthly_credits":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Budget Monthly Credits","description":"Monthly spending cap in credits (None = unlimited)"},"allowed_actions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Actions","description":"Whitelist of billable action IDs (e.g. transcription.start_workflow); None = all"}},"type":"object","required":["label"],"title":"AgentKeyCreateRequest","description":"[CZ] Vytvoreni noveho agent klice."},"AgentKeyCreatedResponse":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"key_prefix":{"type":"string","title":"Key Prefix"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"budget_daily_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Daily Credits"},"budget_monthly_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Monthly Credits"},"allowed_actions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Actions"},"key":{"type":"string","title":"Key","description":"Full API key — shown only once, store it securely"}},"type":"object","required":["id","label","key_prefix","scopes","created_at","key"],"title":"AgentKeyCreatedResponse","description":"[CZ] Odpoved na vytvoreni — jedine misto, kde se vraci plny klic."},"AgentKeyInfo":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"key_prefix":{"type":"string","title":"Key Prefix"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"budget_daily_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Daily Credits"},"budget_monthly_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Monthly Credits"},"allowed_actions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Actions"}},"type":"object","required":["id","label","key_prefix","scopes","created_at"],"title":"AgentKeyInfo","description":"[CZ] Verejna reprezentace klice (bez hashe/plaintextu)."},"AgentKeyListResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/AgentKeyInfo"},"type":"array","title":"Keys"}},"type":"object","required":["keys"],"title":"AgentKeyListResponse"},"Body_upload_audio_audio_files_post":{"properties":{"audio":{"type":"string","contentMediaType":"application/octet-stream","title":"Audio"}},"type":"object","required":["audio"],"title":"Body_upload_audio_audio_files_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"TranscriptionTopupRequest":{"properties":{"package_id":{"type":"string","title":"Package Id","description":"Credit package ID (see GET /credits/packages)"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Success Url","description":"Redirect after successful payment (defaults to app billing)"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Url","description":"Redirect after cancelled payment (defaults to app billing)"}},"type":"object","required":["package_id"],"title":"TranscriptionTopupRequest","description":"[CZ] T339: Human-in-the-loop dobiti kreditu — agent pripravi Stripe\nCheckout, ale platbu potvrzuje CLOVEK (majitel uctu) kliknutim na URL."},"TranscriptionTopupResponse":{"properties":{"payment_url":{"type":"string","title":"Payment Url","description":"Stripe Checkout URL — hand this to the human owner"},"session_id":{"type":"string","title":"Session Id","description":"Stripe Checkout session ID"},"message":{"type":"string","title":"Message","default":"Payment link created. A HUMAN must open payment_url and complete the payment; credits are added automatically afterwards."}},"type":"object","required":["payment_url","session_id"],"title":"TranscriptionTopupResponse","description":"[CZ] Platebni odkaz pro majitele uctu (agent sam platit nemuze)."},"TranscriptionWorkflowCreateRequest":{"properties":{"audio_file_id":{"type":"string","title":"Audio File Id","description":"ID of an uploaded audio file (POST /audio-files)"},"providers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Providers","description":"Transcription providers to use; defaults to server-configured providers"},"diarization_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Diarization Enabled","description":"Speaker diarization on/off (None = provider default)"},"max_duration_seconds":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Max Duration Seconds","description":"Optional cap on processed audio duration (partial transcription)"},"merge_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Merge Config","description":"Optional merge/quality configuration overrides (see docs)"}},"type":"object","required":["audio_file_id"],"title":"TranscriptionWorkflowCreateRequest","description":"[CZ] Spusteni automatickeho workflow (transkripce -> merge -> quality).\n\nMinimalisticky kontrakt pro agenty: povinne je jen `audio_file_id`\nz uploadu. Providery se defaultuji podle konfigurace serveru."},"TranscriptionWorkflowCreateResponse":{"properties":{"workflow_id":{"type":"string","title":"Workflow Id","description":"Workflow ID for status polling and downloads"},"job_ids":{"items":{"type":"string"},"type":"array","title":"Job Ids","description":"Per-provider transcription job IDs"},"message":{"type":"string","title":"Message","default":"Workflow queued"},"idempotency_replayed":{"type":"boolean","title":"Idempotency Replayed","description":"True when this response is a stored replay for the same Idempotency-Key","default":false}},"type":"object","required":["workflow_id","job_ids"],"title":"TranscriptionWorkflowCreateResponse","description":"[CZ] Vysledek spusteni workflow."},"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"}}},"servers":[{"url":"/api/v1/transcription"}]}