{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://mugoft.dev/video-to-notes/contracts/public-api/v1/paid-api.schema.json", "title": "Paid public API v1 (additive, release gated)", "$ref": "#/$defs/job", "$defs": { "empty": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] }, "keyCreate": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "expires_at": { "type": "integer", "minimum": 0 } }, "required": [ "name" ] }, "keyMetadata": { "type": "object", "additionalProperties": false, "properties": { "key_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "masked_key": { "type": "string", "minLength": 1, "maxLength": 80 }, "created_at": { "type": "integer", "minimum": 0 }, "expires_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "last_used_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "key_id", "name", "masked_key", "created_at", "expires_at", "last_used_at", "revoked_at" ] }, "keyCreated": { "type": "object", "additionalProperties": false, "properties": { "key": { "$ref": "#/$defs/keyMetadata" }, "secret": { "type": "string", "pattern": "^vtn_(dev|prod)_[A-Za-z0-9_-]{43,}$" } }, "required": [ "key", "secret" ] }, "keyList": { "type": "object", "additionalProperties": false, "properties": { "keys": { "type": "array", "items": { "$ref": "#/$defs/keyMetadata" }, "maxItems": 100 } }, "required": [ "keys" ] }, "limits": { "type": "object", "additionalProperties": false, "properties": { "max_upload_bytes": { "type": "integer", "minimum": 0, "maximum": 8589934592 }, "max_selection_seconds": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "active_jobs": { "type": "integer", "minimum": 0, "maximum": 1 }, "active_uploads": { "type": "integer", "minimum": 0, "maximum": 1 }, "daily_uploads": { "type": "integer", "minimum": 0 }, "daily_upload_bytes": { "type": "integer", "minimum": 0 }, "new_requests_per_minute": { "type": "integer", "minimum": 0 }, "read_requests_per_minute": { "type": "integer", "minimum": 0 }, "poll_after_seconds": { "type": "integer", "minimum": 0 }, "result_page_bytes": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "result_page_items": { "type": "integer", "minimum": 0, "maximum": 32 }, "upload_url_seconds": { "type": "integer", "minimum": 0, "maximum": 900 }, "download_url_seconds": { "type": "integer", "minimum": 0, "maximum": 600 }, "result_retention_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, "recovery_retention_seconds": { "type": "integer", "minimum": 0, "maximum": 172800 }, "idempotency_retention_seconds": { "type": "integer", "minimum": 0 } }, "required": [ "max_upload_bytes", "max_selection_seconds", "active_jobs", "active_uploads", "daily_uploads", "daily_upload_bytes", "new_requests_per_minute", "read_requests_per_minute", "poll_after_seconds", "result_page_bytes", "result_page_items", "upload_url_seconds", "download_url_seconds", "result_retention_seconds", "recovery_retention_seconds", "idempotency_retention_seconds" ] }, "capabilities": { "type": "object", "additionalProperties": false, "properties": { "api_admission_enabled": { "type": "boolean" }, "key_creation_enabled": { "type": "boolean" }, "server_upload_enabled": { "type": "boolean" }, "long_jobs": { "type": "boolean" }, "formats": { "type": "array", "items": { "enum": [ "mp4", "m4v", "mov", "webm", "mkv", "ogv", "avi", "wmv", "asf", "flv", "mpg", "mpeg", "vob", "ts", "mts", "m2ts", "3gp", "3g2", "mxf", "mp3", "m4a", "aac", "wav", "flac", "ogg", "oga", "opus", "wma", "amr", "aiff", "aif", "caf", "ac3" ] }, "maxItems": 33 }, "audio_languages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 35 }, "maxItems": 200 }, "notes_languages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 35 }, "maxItems": 200 }, "download_formats": { "type": "array", "items": { "enum": [ "transcript_txt", "notes_md", "notes_html", "notes_pdf" ] }, "maxItems": 4 }, "email_opt_in": { "const": false }, "limits": { "$ref": "#/$defs/limits" }, "result_billing": { "type": "boolean" } }, "required": [ "api_admission_enabled", "key_creation_enabled", "server_upload_enabled", "long_jobs", "formats", "audio_languages", "notes_languages", "download_formats", "email_opt_in", "limits" ], "allOf": [ { "if": { "properties": { "long_jobs": { "const": false } }, "required": [ "long_jobs" ] }, "then": { "properties": { "limits": { "properties": { "max_selection_seconds": { "type": "number", "exclusiveMinimum": 0, "maximum": 7200 } } } } } } ] }, "account": { "type": "object", "additionalProperties": false, "properties": { "plan": { "enum": [ "basic", "plus", null ] }, "eligible": { "type": "boolean" }, "remaining_seconds": { "type": "integer", "minimum": 0 }, "allowance_expires_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "capabilities": { "$ref": "#/$defs/capabilities" }, "limit_seconds": { "type": "integer", "minimum": 0 }, "used_seconds": { "type": "integer", "minimum": 0 }, "reserved_seconds": { "type": "integer", "minimum": 0 }, "available_seconds": { "type": "integer", "minimum": 0 } }, "required": [ "plan", "eligible", "remaining_seconds", "allowance_expires_at", "capabilities" ] }, "uploadCreate": { "type": "object", "additionalProperties": false, "properties": { "byte_size": { "type": "integer", "minimum": 1, "maximum": 8589934592 }, "extension": { "enum": [ "mp4", "m4v", "mov", "webm", "mkv", "ogv", "avi", "wmv", "asf", "flv", "mpg", "mpeg", "vob", "ts", "mts", "m2ts", "3gp", "3g2", "mxf", "mp3", "m4a", "aac", "wav", "flac", "ogg", "oga", "opus", "wma", "amr", "aiff", "aif", "caf", "ac3" ], "type": "string" } }, "required": [ "byte_size", "extension" ] }, "uploadParts": { "type": "object", "additionalProperties": false, "properties": { "part_numbers": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 1000 }, "minItems": 1, "maxItems": 100, "uniqueItems": true } }, "required": [ "part_numbers" ] }, "completedPart": { "type": "object", "additionalProperties": false, "properties": { "part_number": { "type": "integer", "minimum": 1, "maximum": 1000 }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "part_number", "etag" ] }, "uploadComplete": { "type": "object", "additionalProperties": false, "properties": { "parts": { "type": "array", "items": { "$ref": "#/$defs/completedPart" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "parts" ] }, "uploadTarget": { "type": "object", "additionalProperties": false, "properties": { "part_number": { "type": "integer", "minimum": 1, "maximum": 1000 }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 8192 }, "expires_at": { "type": "integer", "minimum": 0 } }, "required": [ "part_number", "url", "expires_at" ] }, "uploadTargets": { "type": "object", "additionalProperties": false, "properties": { "upload_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "targets": { "type": "array", "items": { "$ref": "#/$defs/uploadTarget" }, "maxItems": 100 } }, "required": [ "upload_id", "targets" ] }, "upload": { "type": "object", "additionalProperties": false, "properties": { "upload_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "state": { "enum": [ "created", "uploading", "uploaded", "probing", "probed", "failed", "aborted", "expired" ] }, "expires_at": { "type": "integer", "minimum": 0 }, "part_size": { "type": "integer", "minimum": 0 }, "part_count": { "type": "integer", "minimum": 0, "maximum": 1000 }, "error": { "anyOf": [ { "$ref": "#/$defs/errorDetail" }, { "type": "null" } ] } }, "required": [ "upload_id", "state", "expires_at", "part_size", "part_count", "error" ] }, "range": { "type": "object", "additionalProperties": false, "properties": { "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "minimum": 0 } }, "required": [ "start_seconds", "end_seconds" ] }, "jobCreate": { "type": "object", "additionalProperties": false, "properties": { "upload_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "range": { "$ref": "#/$defs/range" }, "audio_language": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 35 }, { "type": "null" } ] }, "notes_language": { "type": "string", "minLength": 1, "maxLength": 35 } }, "required": [ "upload_id" ] }, "resultQuery": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [] }, "errorDetail": { "type": "object", "additionalProperties": false, "properties": { "code": { "enum": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION_ERROR", "PLAN_REQUIRED", "INSUFFICIENT_BALANCE", "CAPABILITY_DISABLED", "UNSUPPORTED_MEDIA", "MEDIA_TOO_LARGE", "PROBE_FAILED", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_EXPIRED", "JOB_CONFLICT", "RESULT_EXPIRED", "RATE_LIMITED", "UNAVAILABLE" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1024 }, "retryable": { "type": "boolean" }, "retry_after_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "context": { "type": "object", "additionalProperties": false, "properties": { "limit_seconds": { "type": "integer", "minimum": 0 }, "used_seconds": { "type": "integer", "minimum": 0 }, "reserved_seconds": { "type": "integer", "minimum": 0 }, "available_seconds": { "type": "integer", "minimum": 0 }, "requested_seconds": { "type": "integer", "minimum": 0 } } } }, "required": [ "code", "message", "retryable", "retry_after_seconds" ] }, "error": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/$defs/errorDetail" }, "request_id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "error", "request_id" ] }, "job": { "type": "object", "additionalProperties": false, "properties": { "job_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "state": { "enum": [ "preparing", "queued", "processing", "completed", "completed_with_gaps", "interrupted", "cancelled", "failed", "expired" ] }, "stage": { "enum": [ "probe", "planning", "admission", "extraction", "transcription", "notes", "publication", "terminal" ] }, "created_at": { "type": "integer", "minimum": 0 }, "expires_at": { "type": "integer", "minimum": 0 }, "result_expires_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "idempotency_expires_at": { "type": "integer", "minimum": 0 }, "poll_after_seconds": { "type": "integer", "minimum": 0 }, "status_url": { "type": "string", "minLength": 1, "maxLength": 512 }, "result_url": { "type": "string", "minLength": 1, "maxLength": 512 }, "completed_units": { "type": "integer", "minimum": 0 }, "total_units": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_seconds": { "type": "integer", "minimum": 0 }, "result_available": { "type": "boolean" }, "can_resume": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 }, "maxItems": 100 }, "error": { "anyOf": [ { "$ref": "#/$defs/errorDetail" }, { "type": "null" } ] }, "settlement": { "description": "Authoritative billing state of one paid operation pinned to billing policy 66.1 (reserve upfront, charge once when the requested result is durably ready). Additive: only operations admitted under 66.1 carry it; recovery policy 50.1 stays independent. Clients never send it and never assert readiness.", "type": "object", "additionalProperties": false, "required": [ "kind", "billing_policy", "recovery_policy", "requested", "attempt", "result", "hold", "charge", "next_action" ], "properties": { "kind": { "const": "paid-settlement-v1" }, "billing_policy": { "const": "66.1" }, "recovery_policy": { "const": "50.1" }, "requested": { "type": "object", "additionalProperties": false, "required": [ "product", "formats" ], "description": "Pinned at admission; a client cannot change it mid-run.", "properties": { "product": { "enum": [ "transcript", "notes" ] }, "formats": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "enum": [ "transcript_txt", "notes_md", "notes_html", "notes_pdf" ] } } } }, "attempt": { "type": "object", "additionalProperties": false, "required": [ "number", "revision" ], "description": "The funded attempt. A retry, a notes-only retry or a resume opens a new number with a fresh hold; it never resets provider budgets.", "properties": { "number": { "type": "integer", "minimum": 0, "maximum": 7 }, "revision": { "type": "integer", "minimum": 0 }, "deadline": { "type": [ "number", "null" ], "minimum": 0, "description": "Immutable wall deadline of this attempt (epoch seconds)." }, "progress_deadline": { "type": [ "number", "null" ], "minimum": 0, "description": "When the hold is released without new meaningful progress (epoch seconds, server clock)." } } }, "result": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "enum": [ "processing", "ready", "failed", "stopped" ], "description": "ready = the server committed readiness proof for the requested product and formats; transcription completing alone is never ready." }, "reason": { "type": [ "string", "null" ], "maxLength": 64 }, "published_at": { "type": [ "number", "null" ], "minimum": 0 }, "expires_at": { "type": [ "number", "null" ], "minimum": 0, "description": "Result downloads end: first owner-accessible publication + 86400 s." } } }, "hold": { "type": "object", "additionalProperties": false, "required": [ "state", "seconds" ], "properties": { "state": { "enum": [ "held", "release_pending", "released", "captured", "none" ], "description": "release_pending: the attempt ended but the ledger has not confirmed the release yet (never shown as available time)." }, "seconds": { "type": "integer", "minimum": 0, "description": "Seconds this attempt reserved before work." } } }, "charge": { "type": "object", "additionalProperties": false, "required": [ "state", "published_seconds" ], "properties": { "state": { "enum": [ "pending", "final" ] }, "published_seconds": { "type": "integer", "minimum": 0, "description": "Cumulative once-only charge for results already published to the owner." }, "attempt_seconds": { "type": [ "integer", "null" ], "description": "Net change made by this attempt's settlement: 0 for a failed attempt, negative for a credit of earlier normal-rate coverage." }, "discounted": { "type": "boolean", "description": "The sticky completed-gap half rate applies." } } }, "next_action": { "enum": [ "none", "wait", "resume", "retry_notes", "retry_delivery" ], "description": "resume = missing audio; retry_notes = notes/exports only, no audio replay; retry_delivery = email only, no inference." }, "resume_available": { "type": "boolean" } } } }, "required": [ "job_id", "state", "stage", "created_at", "expires_at", "result_expires_at", "idempotency_expires_at", "poll_after_seconds", "status_url", "result_url", "completed_units", "total_units", "charged_seconds", "result_available", "can_resume", "warnings", "error" ] }, "segment": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string", "maxLength": 100000 }, "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "minimum": 0 }, "timing_quality": { "enum": [ "aligned", "approximate", "unavailable" ] }, "timing_method": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "text", "start_seconds", "end_seconds", "timing_quality", "timing_method" ] }, "gap": { "type": "object", "additionalProperties": false, "properties": { "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "minimum": 0 }, "reason": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "start_seconds", "end_seconds", "reason" ] }, "resultItem": { "type": "object", "additionalProperties": false, "properties": { "index": { "type": "integer", "minimum": 0 }, "kind": { "enum": [ "transcript", "notes", "gap", "warning" ] }, "text": { "type": "string", "maxLength": 500000 }, "segments": { "type": "array", "items": { "$ref": "#/$defs/segment" }, "maxItems": 1000 }, "gap": { "$ref": "#/$defs/gap" } }, "required": [ "index", "kind" ], "allOf": [ { "if": { "properties": { "kind": { "const": "transcript" } }, "required": [ "kind" ] }, "then": { "required": [ "text" ] } }, { "if": { "properties": { "kind": { "const": "notes" } }, "required": [ "kind" ] }, "then": { "required": [ "text" ] } }, { "if": { "properties": { "kind": { "const": "gap" } }, "required": [ "kind" ] }, "then": { "required": [ "gap" ] } }, { "if": { "properties": { "kind": { "const": "warning" } }, "required": [ "kind" ] }, "then": { "required": [ "text" ] } } ] }, "artifact": { "type": "object", "additionalProperties": false, "properties": { "format": { "enum": [ "transcript_txt", "notes_md", "notes_html", "notes_pdf" ] }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 8192 }, "expires_at": { "type": "integer", "minimum": 0 } }, "required": [ "format", "url", "expires_at" ] }, "result": { "type": "object", "additionalProperties": false, "properties": { "job_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "snapshot": { "type": "string", "minLength": 1, "maxLength": 128 }, "items": { "type": "array", "items": { "$ref": "#/$defs/resultItem" }, "maxItems": 32 }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "null" } ] }, "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifact" }, "maxItems": 4 }, "charged_seconds": { "type": "integer", "minimum": 0 }, "partial": { "type": "boolean" }, "expires_at": { "type": "integer", "minimum": 0 } }, "required": [ "job_id", "snapshot", "items", "next_cursor", "artifacts", "charged_seconds", "partial", "expires_at" ] } }, "x-routes": { "GET /account/api-keys": { "authentication": "website_session", "request": null, "response": "keyList", "success_status": 200, "error": "error" }, "POST /account/api-keys": { "authentication": "website_session", "request": "keyCreate", "response": "keyCreated", "success_status": 201, "error": "error" }, "POST /account/api-keys/{key_id}/revoke": { "authentication": "website_session", "request": "empty", "response": "keyMetadata", "success_status": 200, "error": "error" }, "GET /api/v1/account": { "authentication": "api_key", "request": null, "response": "account", "success_status": 200, "error": "error" }, "POST /api/v1/uploads": { "authentication": "api_key", "request": "uploadCreate", "response": "upload", "success_status": 201, "error": "error" }, "POST /api/v1/uploads/{upload_id}/parts": { "authentication": "api_key", "request": "uploadParts", "response": "uploadTargets", "success_status": 200, "error": "error" }, "POST /api/v1/uploads/{upload_id}/complete": { "authentication": "api_key", "request": "uploadComplete", "response": "upload", "success_status": 200, "error": "error" }, "GET /api/v1/uploads/{upload_id}": { "authentication": "api_key", "request": null, "response": "upload", "success_status": 200, "error": "error" }, "POST /api/v1/uploads/{upload_id}/abort": { "authentication": "api_key", "request": "empty", "response": "upload", "success_status": 200, "error": "error" }, "POST /api/v1/jobs": { "authentication": "api_key", "request": "jobCreate", "response": "job", "success_status": 202, "error": "error" }, "GET /api/v1/jobs/{job_id}": { "authentication": "api_key", "request": null, "response": "job", "success_status": 200, "error": "error" }, "GET /api/v1/jobs/{job_id}/result": { "authentication": "api_key", "request": "resultQuery", "response": "result", "success_status": 200, "error": "error" }, "POST /api/v1/jobs/{job_id}/cancel": { "authentication": "api_key", "request": "empty", "response": "job", "success_status": 200, "error": "error" }, "POST /api/v1/jobs/{job_id}/resume": { "authentication": "api_key", "request": "empty", "response": "job", "success_status": 202, "error": "error" } } }