{ "openapi": "3.1.0", "info": { "title": "UploadCheck.app API", "version": "0.1.0", "description": "Programmatic quality checks for videos, podcasts, clips, uploads, and agent workflows." }, "servers": [ { "url": "https://api.uploadcheck.app" } ], "security": [ { "bearerApiKey": [] } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "Workspace API key supplied as a bearer token." } }, "schemas": { "QcJob": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string" }, "progressPct": { "type": "integer" }, "verdict": { "type": [ "string", "null" ], "enum": [ "PASS", "WATCH", "BLOCK", null ] }, "minutesMetered": { "type": "integer" }, "profile": { "type": [ "string", "null" ], "description": "Effective QC profile after resolving profile:auto or aliases." }, "requestedProfile": { "type": [ "string", "null" ], "description": "Requested profile name before auto inference or alias normalization." }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "processingDurationMs": { "type": "integer", "description": "Wall-clock processing time in milliseconds from job start to completion." }, "failureReason": { "type": [ "string", "null" ], "description": "Failure or fallback reason when the engine cannot complete normally." }, "statusUrl": { "type": "string" }, "reportUrl": { "type": "string" }, "observability": { "type": [ "object", "null" ], "description": "Timing, engine, stage, provider-usage, and failure telemetry for job debugging and cost analysis.", "properties": { "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "processingDurationMs": { "type": "integer" }, "outcome": { "type": [ "string", "null" ] }, "engine": { "type": [ "string", "null" ] }, "providerUsageEntries": { "type": "integer" }, "failureReason": { "type": [ "string", "null" ] }, "stages": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "progressPct": { "type": "integer" }, "elapsedMs": { "type": "integer" }, "at": { "type": "string", "format": "date-time" } } } } } }, "mediaIngress": { "type": [ "object", "null" ], "description": "Sanitized media ingress metadata. Inline media is processed ephemerally without exposing temporary server paths.", "properties": { "mode": { "type": "string", "enum": [ "inline_ephemeral", "signed_upload", "youtube_url", "remote_url", "local_or_remote_source" ] }, "contentType": { "type": [ "string", "null" ] }, "bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ], "description": "SHA-256 hash of the checked media bytes when UploadCheck handled the bytes directly." }, "ephemeral": { "type": "boolean" }, "storageMode": { "type": "string", "enum": [ "render_temp_storage", "durable_filesystem", "object_storage" ] } } }, "sidecarIngress": { "type": [ "object", "null" ], "description": "Sanitized sidecar ingress metadata. Remote sidecar URLs are fetched into temporary storage for the run and are never exposed in public job responses.", "properties": { "mode": { "type": "string", "enum": [ "remote_https_sidecars" ] }, "ephemeral": { "type": "boolean" }, "supplied": { "type": "array", "items": { "type": "string", "enum": [ "manifest", "transcript", "watchlist", "expectedScript", "chunkSidecars" ] } }, "neverExposes": { "type": "array", "items": { "type": "string" } } } }, "sourceRedacted": { "type": "boolean", "description": "True when an upload-backed local server path was removed from the public job response." }, "costEstimate": { "type": "object", "properties": { "estimatedCogsUsd": { "type": "number" }, "grossMarginBudgetUsd": { "type": "number" }, "grossMarginTargetPct": { "type": "number" }, "withinBudget": { "type": "boolean" }, "modelCheckCents": { "type": "number" }, "modelBackedChecks": { "type": "array", "items": { "type": "string" } }, "maxAiReviewSecondsAtMargin": { "type": "integer" }, "marginSafe": { "type": "boolean" } } } }, "required": [ "jobId", "status", "progressPct", "verdict", "minutesMetered" ] }, "ApiKeyRecord": { "type": "object", "properties": { "keyId": { "type": "string" }, "name": { "type": "string" }, "workspaceId": { "type": "string" }, "ownerEmail": { "type": [ "string", "null" ] }, "provisioningId": { "type": [ "string", "null" ] }, "checkoutCustomerId": { "type": [ "string", "null" ] }, "checkoutSubscriptionId": { "type": [ "string", "null" ] }, "tokenPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "planId": { "type": [ "string", "null" ] }, "includedMinutes": { "type": [ "integer", "null" ] }, "planPriceCents": { "type": [ "integer", "null" ] }, "overageCapCents": { "type": [ "integer", "null" ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "AbuseEvent": { "type": "object", "properties": { "eventId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "integer" }, "workspaceId": { "type": [ "string", "null" ] }, "ownerEmail": { "type": [ "string", "null" ] }, "planId": { "type": [ "string", "null" ] }, "includedMinutes": { "type": [ "integer", "null" ] }, "minutesUsed": { "type": [ "integer", "null" ] }, "requestedMinutes": { "type": [ "integer", "null" ] }, "minutesRemaining": { "type": [ "integer", "null" ] }, "maxDurationMinutes": { "type": [ "integer", "null" ] }, "maxUploadMb": { "type": [ "integer", "null" ] }, "maxActiveJobs": { "type": [ "integer", "null" ] } } }, "SpendAlert": { "type": "object", "properties": { "alertId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": [ "string", "null" ] }, "ownerEmail": { "type": [ "string", "null" ] }, "planId": { "type": [ "string", "null" ] }, "billingPeriod": { "type": [ "string", "null" ] }, "minutesUsed": { "type": [ "integer", "null" ] }, "includedMinutes": { "type": [ "integer", "null" ] }, "planPriceCents": { "type": [ "integer", "null" ] }, "overageRevenueCents": { "type": [ "integer", "null" ], "description": "Billable extra-minute spend at the plan overage rate; this is the alert trigger value." }, "overageRateCentsPerMinute": { "type": [ "number", "null" ], "description": "Customer overage price in cents per minute for the plan." }, "overageCostCents": { "type": [ "number", "null" ], "description": "Estimated overage COGS retained as audit context, not the trigger value." }, "observedTotalCogsCents": { "type": [ "number", "null" ] }, "status": { "type": "string", "enum": [ "sent", "failed", "skipped" ] }, "provider": { "type": [ "string", "null" ] }, "providerMessageId": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } } }, "Upload": { "type": "object", "properties": { "uploadId": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "workspaceId": { "type": [ "string", "null" ], "description": "Workspace that owns this upload reservation. Stored workspace API keys are pinned to this value." }, "ownerEmail": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "created", "uploaded" ] }, "signedPutUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "storageMode": { "type": "string", "enum": [ "render_temp_storage", "durable_filesystem", "object_storage" ] }, "objectKey": { "type": "string", "nullable": true }, "objectUrl": { "type": "string", "nullable": true } } }, "UploadStored": { "type": "object", "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded" ] }, "storageMode": { "type": "string", "enum": [ "render_temp_storage", "durable_filesystem", "object_storage" ] }, "bytesReceived": { "type": "integer" }, "sha256": { "type": "string" }, "objectKey": { "type": "string" }, "objectUrl": { "type": "string" } }, "required": [ "uploadId", "status", "storageMode", "bytesReceived", "sha256" ] }, "WebhookEndpoint": { "type": "object", "properties": { "webhookId": { "type": "string" }, "url": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "workspaceId": { "type": [ "string", "null" ], "description": "Workspace that owns this webhook endpoint. Stored workspace API keys are pinned to this value." }, "ownerEmail": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "signingSecretPreview": { "type": "string" }, "signingSecret": { "type": "string", "description": "Returned once on creation." }, "signingSecretStorage": { "type": "string", "enum": [ "encrypted", "plaintext" ] } } }, "WebhookDelivery": { "type": "object", "properties": { "deliveryId": { "type": "string" }, "webhookId": { "type": "string" }, "eventType": { "type": "string" }, "jobId": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ], "description": "Workspace that owns this delivery. Stored workspace API keys can only list, retry, or drain their own deliveries." }, "ownerEmail": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "sent", "failed" ] }, "url": { "type": "string" }, "attemptCount": { "type": "integer" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "responseStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "signatureHeader": { "type": "string", "const": "X-UploadCheck-Signature" }, "signature": { "type": "string" }, "payload": { "type": "object" } } }, "WebhookDeliveryList": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "deliveries" ] }, "WebhookDrainResult": { "type": "object", "properties": { "processed": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "processed", "results" ] } } }, "paths": { "/healthz": { "get": { "summary": "Health check", "security": [], "responses": { "200": { "description": "Service is healthy" } } } }, "/v1/readiness": { "get": { "summary": "Launch readiness and operational configuration status", "security": [], "responses": { "200": { "description": "No-secret readiness report for checkout, custom domain, persistence, storage, and Product Hunt launch state" } } } }, "/v1/launch-status": { "get": { "summary": "Live Product Hunt launch status", "security": [], "responses": { "200": { "description": "Live machine-readable launch go/no-go state derived from readiness checks, including completed controls, current blockers, and operator commands.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/launch-handoff": { "get": { "summary": "Live Product Hunt launch handoff", "security": [], "responses": { "200": { "description": "Live operator and agent handoff derived from readiness checks, including current blockers, required actions, proof commands, and the no-launch rule.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/launch-doctor": { "get": { "summary": "Live Product Hunt launch doctor", "security": [], "responses": { "200": { "description": "Live blocker fix plan and normalized launch-doctor command coverage derived from readiness checks.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/launch-evidence": { "get": { "summary": "Redacted live Product Hunt launch evidence", "security": [], "responses": { "200": { "description": "Redacted launch evidence bundle derived from the live launch doctor, suitable for agents and public Product Hunt readiness audits.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent-manifest.json": { "get": { "summary": "UploadCheck agent manifest", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest for MCP, CLI, API, pricing, and launch metadata.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp-install.json": { "get": { "summary": "UploadCheck MCP install manifest", "security": [], "responses": { "200": { "description": "Machine-readable install snippets for Codex, Claude Desktop, Cursor, and generic MCP clients.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/pipeline-handoff.json": { "get": { "summary": "UploadCheck production pipeline handoff", "security": [], "responses": { "200": { "description": "Machine-readable runbook for NTO/NPO and creator production pipelines that call UploadCheck.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/pipeline-recipes.json": { "get": { "summary": "UploadCheck pipeline recipes", "security": [], "responses": { "200": { "description": "Machine-readable NTO/NPO and creator pipeline profiles.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/npo-pipeline-handoff.json": { "get": { "summary": "UploadCheck NPO pipeline handoff", "security": [], "responses": { "200": { "description": "Focused callable runbook for NPO podcast/audio production pipelines.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/launch-targets.json": { "get": { "summary": "UploadCheck launch targets", "security": [], "responses": { "200": { "description": "Machine-readable Render service IDs, DNS records, HTTP targets, and verification commands.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/launch-status.json": { "get": { "summary": "UploadCheck launch status", "security": [], "responses": { "200": { "description": "Machine-readable Product Hunt launch go/no-go state, completed controls, remaining blockers, and operator commands.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/product-hunt-launch-kit.json": { "get": { "summary": "Product Hunt launch kit", "security": [], "responses": { "200": { "description": "Machine-readable Product Hunt launch copy, demo flow, proof links, pricing posture, and go/no-go rule.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/cost-basis.json": { "get": { "summary": "UploadCheck cost basis", "security": [], "responses": { "200": { "description": "Machine-readable cost-per-minute, plan, and gross-margin assumptions.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/llms.txt": { "get": { "summary": "UploadCheck llms.txt", "security": [], "responses": { "200": { "description": "Text guidance for answer engines and coding agents.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/sample-reports/index.json": { "get": { "summary": "Public UploadCheck sample report index", "security": [], "responses": { "200": { "description": "PASS, WATCH, and BLOCK sample report artifacts.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/qc/estimate": { "post": { "summary": "Preflight cost and margin estimate", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minutes": { "type": "number" }, "duration_seconds": { "type": "number" }, "profile": { "description": "Optional QC profile. Use auto to infer from media kind/duration, or pass nto_long_form, generic_creator_video, shorts, audio, npo_podcast_or_audio, or thumbnail.", "type": "string", "enum": [ "auto", "nto_long_form", "generic_creator_video", "shorts", "audio", "npo_podcast_or_audio", "thumbnail" ] }, "checks": { "type": "string" }, "plan_id": { "type": "string" }, "plan_price_cents": { "type": "integer" }, "included_minutes": { "type": "integer" }, "ai_review_seconds": { "type": "number" }, "cost_guardrail": { "type": "string", "enum": [ "downgrade", "block", "off" ] } } } } } }, "responses": { "200": { "description": "Cost estimate and effective guardrail behavior" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient scope" } } } }, "/v1/qc/jobs": { "post": { "summary": "Create a QC job", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "youtube_url": { "type": "string" }, "upload_id": { "type": "string" }, "signed_url": { "type": "string" }, "callback_url": { "type": "string" }, "idempotency_key": { "type": "string" }, "media_base64": { "type": "string" }, "media_content_type": { "type": "string" }, "media_kind": { "type": "string", "enum": [ "video", "audio", "image" ] }, "video_base64": { "type": "string" }, "video_content_type": { "type": "string" }, "audio_base64": { "type": "string" }, "audio_content_type": { "type": "string" }, "data_url": { "type": "string" }, "filename": { "type": "string" }, "process_async": { "description": "When true, leave the job queued for POST /v1/qc/jobs/drain instead of running QC in the create request. Inline media and inline sidecars are not supported in queued mode.", "type": "boolean" }, "duration_seconds": { "description": "Declared media duration used for cost, usage, and abuse-limit preflight.", "type": "number" }, "profile": { "description": "Optional QC profile. Use auto to infer from media kind/duration, or pass nto_long_form, generic_creator_video, shorts, audio, npo_podcast_or_audio, or thumbnail. Explicit checks override profile defaults.", "type": "string", "enum": [ "auto", "nto_long_form", "generic_creator_video", "shorts", "audio", "npo_podcast_or_audio", "thumbnail" ] }, "size_bytes": { "description": "Declared media size used for upload abuse-limit preflight.", "type": "integer" }, "manifest_json": { "description": "Optional storybook/edit manifest JSON used by repeat_fatigue for visual reuse and source-family analysis.", "type": [ "object", "array", "string" ] }, "manifest_base64": { "description": "Optional base64-encoded storybook/edit manifest JSON.", "type": "string" }, "manifest_filename": { "type": "string" }, "manifest_url": { "description": "HTTPS URL for a remote storybook/edit manifest. Use for process_async jobs because inline sidecars are ephemeral.", "type": "string" }, "transcript_text": { "description": "Optional transcript/script text used by spoken_leaks without ASR spend.", "type": "string" }, "transcript_json": { "description": "Optional transcript JSON with text or words fields used by spoken_leaks.", "type": [ "object", "array", "string" ] }, "transcript_base64": { "description": "Optional base64-encoded transcript text or JSON.", "type": "string" }, "transcript_filename": { "type": "string" }, "transcript_url": { "description": "HTTPS URL for a remote transcript text or JSON sidecar. Use for process_async jobs because inline sidecars are ephemeral.", "type": "string" }, "watchlist_json": { "description": "Optional pronunciation/term watchlist JSON for pronunciation_watchlist.", "type": [ "object", "array", "string" ] }, "watchlist_base64": { "description": "Optional base64-encoded pronunciation/term watchlist JSON.", "type": "string" }, "watchlist_filename": { "type": "string" }, "watchlist_url": { "description": "HTTPS URL for a remote pronunciation/term watchlist JSON sidecar. Use for process_async jobs because inline sidecars are ephemeral.", "type": "string" }, "expected_script_text": { "description": "Optional locked script text used by script_faithfulness with transcript_text/transcript_json.", "type": "string" }, "expected_script_json": { "description": "Optional locked script JSON with text, script, or words fields used by script_faithfulness.", "type": [ "object", "array", "string" ] }, "expected_script_base64": { "description": "Optional base64-encoded locked script text or JSON.", "type": "string" }, "expected_script_filename": { "type": "string" }, "expected_script_url": { "description": "HTTPS URL for a remote locked-script text or JSON sidecar. Use for process_async jobs because inline sidecars are ephemeral.", "type": "string" }, "chunk_sidecars_json": { "description": "Optional array or object map of chunk QC sidecar JSON files used by chunk_sidecar_failures, for example packaged *.garble-report.json entries.", "type": [ "array", "object", "string" ] }, "chunk_sidecars_base64": { "description": "Optional base64-encoded JSON array or object map of chunk QC sidecar files.", "type": "string" }, "chunk_sidecar_dirname": { "type": "string" }, "chunk_sidecars_url": { "description": "HTTPS URL for a remote JSON array or object map of chunk QC sidecars. Use for process_async jobs because inline sidecars are ephemeral.", "type": "string" }, "plan_id": { "description": "Optional plan preset for cost estimates and margin guardrails: creator, studio, network, or stress_99_5000.", "type": "string" }, "plan_price_cents": { "description": "Optional custom monthly plan price in cents for cost guardrail calculations.", "type": "integer" }, "included_minutes": { "description": "Optional included monthly checked minutes for cost guardrail calculations.", "type": "integer" }, "ai_review_seconds": { "description": "Internal or explicitly authorized model-review seconds for cost guardrails. Public included minutes are quality QC minutes.", "type": "number" }, "cost_guardrail": { "description": "Margin guardrail behavior when requested AI review would break the >95% gross-margin target.", "type": "string", "enum": [ "downgrade", "block", "off" ] }, "checks": { "type": "string" } } } } } }, "responses": { "200": { "description": "Existing idempotent job returned" }, "202": { "description": "Job queued" }, "413": { "description": "Duration or upload-size abuse limit exceeded" }, "429": { "description": "Active job concurrency limit exceeded" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient scope" } } }, "get": { "summary": "List recent QC jobs", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "source_url", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent jobs" } } } }, "/v1/qc/jobs/drain": { "post": { "summary": "Drain queued async QC jobs", "description": "Processes queued async QC jobs. Stored workspace API keys drain only jobs owned by their own workspace; operator/admin bearer keys can drain globally.", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 25 } } } } } }, "responses": { "200": { "description": "Queued jobs processed" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient scope" } } } }, "/v1/qc/jobs/{job_id}": { "get": { "summary": "Get QC job status", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status" } } } }, "/v1/qc/jobs/{job_id}/report": { "get": { "summary": "Get QC report", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timestamped report" } }, "description": "Returns schemaVersion, verdict (PASS|WATCH|BLOCK), usage, costEstimate, and flags[]. Every flag includes gate, severity, timestamp, summary, evidence, and a deterministic repair object ({ action, instruction, verify }) the calling agent can act on directly." } }, "/v1/qc/jobs/{job_id}/events": { "get": { "summary": "List QC lifecycle events for a job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lifecycle events" } } } }, "/v1/qc/jobs/{job_id}/artifacts": { "get": { "summary": "List report artifacts for a job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artifacts" } } } }, "/v1/qc/jobs/{job_id}/artifacts/markers": { "get": { "summary": "Download editor marker export CSV", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV marker export", "content": { "text/csv": { "schema": { "type": "string" } } } } } } }, "/v1/qc/jobs/{job_id}/gate-verdict": { "post": { "summary": "Import an external full-video gate verdict", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "SHIP-OK", "BLOCK", "PASS" ] }, "blocked": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "string" } }, "per_check": { "type": "object" } } } } } }, "responses": { "200": { "description": "Gate verdict imported" }, "404": { "description": "Job not found" } } } }, "/v1/usage": { "get": { "summary": "List recent usage ledger entries", "description": "Operator/admin bearer keys can review recent usage globally. Stored workspace API keys are pinned to their own workspace usage ledger.", "responses": { "200": { "description": "Usage ledger entries" } } } }, "/v1/usage/margins": { "get": { "summary": "Owner/admin usage economics telemetry", "description": "Restricted owner/operator endpoint for internal pricing and margin review. Public customer agents should use GET /v1/usage for metered usage and must not rely on UploadCheck internal economics fields.", "parameters": [ { "name": "billing_period", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Restricted owner/operator usage economics summary" }, "403": { "description": "Insufficient scope for workspace customer keys" } } } }, "/v1/abuse-events": { "get": { "summary": "List persisted abuse-limit events", "description": "Returns fail-fast duration, upload-size, active-job, and usage-limit events for operator dashboard review. Stored workspace API keys are pinned to their own workspace even if a different workspace_id query parameter is supplied.", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "Persisted abuse-limit events, including usage_limit_exceeded plan/minute context when applicable", "content": { "application/json": { "schema": { "type": "object", "properties": { "abuseEvents": { "type": "array", "items": { "$ref": "#/components/schemas/AbuseEvent" } } } } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "API key lacks api_keys:read scope" } } } }, "/v1/spend-alerts": { "get": { "summary": "List persisted overage spend alerts", "description": "Returns Resend owner alert attempts for workspaces whose billable extra-minute spend crossed 100% of subscription value. Responses include billable overage spend and overage COGS audit context. Stored workspace API keys are pinned to their own workspace even if a different workspace_id query parameter is supplied.", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "Persisted spend alerts with status, provider, owner email, minutes, billable overage spend, overage rate, and COGS audit context", "content": { "application/json": { "schema": { "type": "object", "properties": { "spendAlerts": { "type": "array", "items": { "$ref": "#/components/schemas/SpendAlert" } } } } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "API key lacks api_keys:read scope" } } } }, "/v1/api-keys": { "post": { "summary": "Create a workspace API key", "description": "Creates a bearer key for agent clients. The raw apiKey is returned once; persisted records store only a SHA-256 hash and token prefix. Operator/admin bearer keys can provision any workspace; stored workspace API keys with api_keys:write are pinned to their own workspace, owner, plan economics, and overage cap even if another workspace, owner, plan, or cap is supplied.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "workspace_id": { "type": "string" }, "owner_email": { "type": "string" }, "plan_id": { "type": "string" }, "included_minutes": { "type": "integer" }, "plan_price_cents": { "type": "integer" }, "overage_cap_cents": { "type": "integer", "description": "Approved extra-minute spend cap in cents after included deterministic minutes are exhausted. Zero or omitted means block at included minutes." }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "API key created; raw apiKey is shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "key": { "$ref": "#/components/schemas/ApiKeyRecord" }, "warning": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid admin API key" }, "403": { "description": "API key lacks api_keys:write scope" } } }, "get": { "summary": "List workspace API keys", "description": "Operator/admin bearer keys can review redacted API keys globally or by workspace_id. Stored workspace API keys with api_keys:read are pinned to their own workspace even if a different workspace_id query parameter is supplied.", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redacted API key records", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyRecord" } } } } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "API key lacks api_keys:read scope" } } } }, "/v1/checkout/provision-api-key": { "post": { "summary": "Provision a checkout customer API key", "description": "Authenticated provisioning endpoint for checkout/webhook/account flows. It applies UploadCheck plan economics server-side and returns the raw apiKey only on the first successful provisioning call. Optional overage_cap_cents approves extra-minute spend after included deterministic minutes; zero or omitted blocks at included minutes. Stored workspace API keys with api_keys:write are pinned to their own workspace, owner, plan economics, and overage cap before checkout provisioning. Idempotent retries return the redacted key record without the bearer secret.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "plan_id", "owner_email" ], "properties": { "plan_id": { "type": "string", "enum": [ "creator", "studio", "network" ] }, "owner_email": { "type": "string" }, "workspace_id": { "type": "string" }, "checkout_customer_id": { "type": "string" }, "checkout_subscription_id": { "type": "string" }, "overage_cap_cents": { "type": "integer" }, "provisioning_id": { "type": "string", "description": "Optional idempotency key. Defaults to checkout::." } } } } } }, "responses": { "201": { "description": "Provisioned API key; raw apiKey is shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": [ "string", "null" ] }, "key": { "$ref": "#/components/schemas/ApiKeyRecord" }, "idempotentReplay": { "type": "boolean" }, "warning": { "type": "string" } } } } } }, "200": { "description": "Existing provisioning record returned without bearer secret." }, "400": { "description": "Invalid plan or missing owner email" }, "401": { "description": "Missing or invalid provisioning API key" }, "403": { "description": "API key lacks api_keys:write scope" } } } }, "/v1/webhooks/lemonsqueezy": { "post": { "summary": "Receive Lemon Squeezy checkout webhooks", "description": "Verifies Lemon Squeezy X-Signature with HMAC-SHA256 over the raw body using UPLOADCHECK_LEMONSQUEEZY_WEBHOOK_SECRET, then provisions paid subscription/order events into idempotent workspace API keys for MCP/API clients.", "security": [], "parameters": [ { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Lemon Squeezy HMAC-SHA256 hex digest of the raw request body." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Webhook verified and first-time API key provisioned." }, "200": { "description": "Webhook verified and ignored or idempotently replayed without bearer secret." }, "401": { "description": "Invalid Lemon Squeezy signature." }, "503": { "description": "Webhook signing secret is not configured." } } } }, "/v1/qc/jobs/{job_id}/cancel": { "post": { "summary": "Cancel a QC job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job cancelled" } } } }, "/v1/uploads": { "post": { "summary": "Create a signed upload target", "description": "Creates a signed upload reservation. Stored workspace API keys force server-side workspace, owner, and key metadata onto the upload, ignoring client-supplied workspace fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" } }, "required": [ "filename", "content_type", "size_bytes" ] } } } }, "responses": { "201": { "description": "Signed upload target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "413": { "description": "Upload reservation exceeds configured maximum size" } } } }, "/v1/uploads/{upload_id}": { "get": { "summary": "Get upload metadata and processing status", "description": "Returns upload status. Stored workspace API keys can only read upload reservations owned by their own workspace.", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "404": { "description": "Upload not found" } } } }, "/v1/uploads/{upload_id}/content": { "put": { "summary": "Upload local media bytes to a signed UploadCheck URL", "security": [], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Upload bytes stored for a QC job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStored" } } } }, "403": { "description": "Invalid upload token" }, "410": { "description": "Upload URL expired" }, "413": { "description": "Upload too large" }, "404": { "description": "Upload not found" } } } }, "/v1/webhooks": { "post": { "summary": "Register a workspace webhook endpoint", "description": "Registers a signed webhook endpoint. Stored workspace API keys force server-side workspace, owner, and key metadata onto the endpoint, ignoring client-supplied workspace fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Webhook registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } }, "/v1/webhooks/{webhook_id}/delivery-preview": { "get": { "summary": "Preview signed webhook delivery metadata", "description": "Creates a signed preview delivery. Stored workspace API keys can preview only webhook endpoints owned by their own workspace.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed delivery preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "404": { "description": "Webhook not found" } } } }, "/v1/webhooks/deliveries": { "get": { "summary": "List recent webhook deliveries", "description": "Lists webhook delivery attempts. Stored workspace API keys are pinned to their own workspace delivery log even if another webhook_id is supplied.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed" ] } }, { "name": "webhook_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook delivery log entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } } } } }, "/v1/webhooks/deliveries/{delivery_id}/retry": { "post": { "summary": "Retry a pending or failed webhook delivery", "description": "Retries a delivery. Stored workspace API keys can retry only deliveries owned by their own workspace.", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery attempt result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "404": { "description": "Delivery not found" } } } }, "/v1/webhooks/deliveries/drain": { "post": { "summary": "Process due pending webhook deliveries", "description": "Processes due deliveries. Stored workspace API keys drain only pending deliveries owned by their own workspace; operator/admin bearer keys can drain globally.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 25 } } } } } }, "responses": { "200": { "description": "Due delivery drain result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDrainResult" } } } } } } }, "/v1/health/engine": { "get": { "summary": "Engine capability health", "description": "Reports whether the QC engine can run on this deployment: ffmpeg/ffprobe/python/yt-dlp/engine-script capability with ok|degraded|down status and a degraded_reason. No auth required; cached ~5 minutes. Agents should pre-flight this (or read engineStatus on /v1/qc/estimate) before uploading media.", "responses": { "200": { "description": "Engine capability status" } } } } } }