{"openapi":"3.1.0","info":{"title":"Impress Isolated Agent Media API","version":"2.0.0","description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes. Private server-to-server media intake, source-language transcription, and dubbing paid over Lightning L402. Inputs and outputs never become Impress creator records."},"servers":[{"url":"https://agents-api.plebtv.com/v1"}],"tags":[{"name":"Discovery"},{"name":"Sources"},{"name":"Jobs"},{"name":"Artifacts"}],"paths":{"/sources":{"post":{"tags":["Sources"],"summary":"Create a quarantined source","description":"Requires Idempotency-Key. URL and page intake is rate/capacity limited. Upload mode returns multipart instructions.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceCreateRequest"},"examples":{"directUrl":{"value":{"mode":"url","url":"https://media.example/interview.mp4","rightsAttestation":{"version":"2026-07-01","accepted":true,"basis":"owner_or_authorized"}}},"upload":{"value":{"mode":"upload","filename":"interview.mp4","contentType":"video/mp4","sizeBytes":10485760,"sha256":"64-lowercase-hex-characters","rightsAttestation":{"version":"2026-07-01","accepted":true,"basis":"owner_or_authorized"}}}}}}},"responses":{"200":{"description":"Idempotent replay of the existing source","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceCreated"}}}},"201":{"description":"Source accepted","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceCreated"}}}},"400":{"description":"Invalid source request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency or source state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Declared input exceeds service limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or intake capacity exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/sources/{sourceId}":{"get":{"tags":["Sources"],"summary":"Read source scan/probe status","security":[{"sourceToken":[]}],"parameters":[{"$ref":"#/components/parameters/SourceId"}],"responses":{"200":{"description":"Current source state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"401":{"description":"Missing or invalid source token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Source not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false},"delete":{"tags":["Sources"],"summary":"Delete retained source media","security":[{"sourceToken":[]}],"parameters":[{"$ref":"#/components/parameters/SourceId"}],"responses":{"204":{"description":"Source media scheduled for deletion"},"401":{"description":"Missing or invalid source token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Source has a job that is still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/sources/{sourceId}/parts/{partNumber}":{"post":{"tags":["Sources"],"summary":"Sign one upload part","security":[{"sourceToken":[]}],"parameters":[{"$ref":"#/components/parameters/SourceId"},{"name":"partNumber","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":10000}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sizeBytes","sha256"],"properties":{"sizeBytes":{"type":"integer","minimum":1,"maximum":16777216},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}},"responses":{"200":{"description":"Short-lived signed PUT URL","content":{"application/json":{"schema":{"type":"object","required":["uploadUrl","requiredHeaders","expiresAt"],"properties":{"uploadUrl":{"type":"string","format":"uri"},"requiredHeaders":{"type":"object","additionalProperties":false,"required":["content-length","x-amz-checksum-sha256"],"properties":{"content-length":{"type":"string","pattern":"^[0-9]+$"},"x-amz-checksum-sha256":{"type":"string"}}},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid range or checksum","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate or invalid upload state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/sources/{sourceId}/complete":{"post":{"tags":["Sources"],"summary":"Complete multipart upload and queue quarantine scan","security":[{"sourceToken":[]}],"parameters":[{"$ref":"#/components/parameters/SourceId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parts"],"properties":{"parts":{"type":"array","minItems":1,"items":{"type":"object","required":["partNumber","etag","sizeBytes","sha256"],"properties":{"partNumber":{"type":"integer"},"etag":{"type":"string"},"sizeBytes":{"type":"integer"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}}}}},"responses":{"202":{"description":"Completion verified and scanning queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"400":{"description":"Missing, duplicate, or mismatched parts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Completed upload exceeds declared or maximum size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/jobs/scribe":{"post":{"tags":["Jobs"],"summary":"Quote, pay, or recover a source-language transcript job","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{},{"l402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceId","sourceToken"],"properties":{"sourceId":{"type":"string"},"sourceToken":{"type":"string","writeOnly":true,"description":"Opaque source token returned at source creation."},"sourceLanguage":{"type":"string","enum":["auto","en","es","pt","fr","de","it","ru","ja","ko","hi","zh","ar"],"default":"auto","description":"Input-audio hint. This is not a translation target."},"l402Authorization":{"type":"string","writeOnly":true,"description":"Protected-body alternative to the Authorization header."}}}}}},"responses":{"202":{"description":"Paid job accepted and durable receipt returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"description":"Source not READY or source reuse window ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/jobs/dub":{"post":{"tags":["Jobs"],"summary":"Quote, pay, or recover a Dub job","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"security":[{},{"l402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceId","sourceToken","targetLanguage","rightsAttestation"],"properties":{"sourceId":{"type":"string"},"sourceToken":{"type":"string","writeOnly":true,"description":"Opaque source token returned at source creation."},"targetLanguage":{"type":"string","enum":["es","pt","fr","de","it","ru","ja","ko","hi","zh","ar"]},"rightsAttestation":{"$ref":"#/components/schemas/RightsAttestation"},"l402Authorization":{"type":"string","writeOnly":true}}}}}},"responses":{"202":{"description":"Paid job accepted and durable receipt returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"description":"Source not READY or source reuse window ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/jobs/{jobId}":{"get":{"tags":["Jobs"],"summary":"Poll private job state","security":[{"agentReceipt":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"State is worker-owned; polling is observational and is not required for completion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing or invalid receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Receipt belongs to a different job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false},"delete":{"tags":["Jobs"],"summary":"Delete retained output media","security":[{"agentReceipt":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"204":{"description":"Artifacts scheduled for deletion; audit row retained"},"409":{"description":"Job is still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/jobs/{jobId}/artifacts":{"get":{"tags":["Artifacts"],"summary":"List five-minute signed artifact downloads","security":[{"agentReceipt":[]}],"parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Private artifact list","content":{"application/json":{"schema":{"type":"object","required":["artifacts"],"properties":{"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}}}}}}},"409":{"description":"Job is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Discovery is online. New isolated processing intake is temporarily unavailable; do not upload media or pay an invoice until this status changes.","headers":{"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store, max-age=0"}},"Retry-After":{"required":true,"schema":{"type":"integer","const":300}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-currently-available":false}},"/languages":{"get":{"tags":["Discovery"],"summary":"List Dub targets and Scribe source hints","responses":{"200":{"description":"Language catalogs"}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI JSON"}}}},"/SKILL.md":{"get":{"tags":["Discovery"],"summary":"Agent integration skill","responses":{"200":{"description":"Markdown skill"}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Concise machine discovery","responses":{"200":{"description":"Plain text discovery"}}}}},"components":{"securitySchemes":{"sourceToken":{"type":"http","scheme":"bearer","bearerFormat":"opaque-source-token","description":"Opaque source-scoped token returned once at source creation."},"l402":{"type":"http","scheme":"L402","description":"L402 <challenge-token>:<payment-preimage>. Never place this credential in a URL."},"agentReceipt":{"type":"http","scheme":"AgentReceipt","description":"Durable job-scoped receipt returned after payment redemption."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}},"SourceId":{"name":"sourceId","in":"path","required":true,"schema":{"type":"string"}},"JobId":{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"PaymentRequired":{"description":"Lightning payment required","headers":{"WWW-Authenticate":{"required":true,"schema":{"type":"string"},"description":"L402 token and BOLT11 invoice challenge."},"Cache-Control":{"required":true,"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentChallenge"}}}}},"schemas":{"RightsAttestation":{"type":"object","additionalProperties":false,"required":["version","accepted","basis"],"properties":{"version":{"type":"string","const":"2026-07-01"},"accepted":{"type":"boolean","const":true},"basis":{"type":"string","enum":["owner_or_authorized","public_domain","licensed"]}}},"SourceCreateRequest":{"oneOf":[{"type":"object","additionalProperties":false,"required":["mode","filename","contentType","sizeBytes","sha256","rightsAttestation"],"properties":{"mode":{"type":"string","const":"upload"},"filename":{"type":"string","minLength":1,"maxLength":200},"contentType":{"type":"string","minLength":1,"maxLength":200},"sizeBytes":{"type":"integer","minimum":1,"maximum":201326592},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"rightsAttestation":{"$ref":"#/components/schemas/RightsAttestation"}}},{"type":"object","additionalProperties":false,"required":["mode","url","rightsAttestation"],"properties":{"mode":{"type":"string","const":"url"},"url":{"type":"string","format":"uri","maxLength":4096},"rightsAttestation":{"$ref":"#/components/schemas/RightsAttestation"}}},{"type":"object","additionalProperties":false,"required":["mode","url","rightsAttestation"],"properties":{"mode":{"type":"string","const":"page"},"url":{"type":"string","format":"uri","maxLength":4096,"description":"YouTube, youtu.be, or Vimeo page URL."},"rightsAttestation":{"$ref":"#/components/schemas/RightsAttestation"}}}]},"SourceCreated":{"allOf":[{"$ref":"#/components/schemas/Source"},{"type":"object","required":["sourceToken","multipart","replayed"],"properties":{"sourceToken":{"type":"string","readOnly":true,"description":"Opaque source credential returned with the source response."},"replayed":{"type":"boolean"},"multipart":{"type":["object","null"],"properties":{"uploadId":{"type":"string"},"partSizeBytes":{"type":"integer"}}}}}]},"Source":{"type":"object","required":["sourceId","mode","status","createdAt","expiresAt"],"properties":{"sourceId":{"type":"string"},"mode":{"type":"string","enum":["upload","url","page"]},"status":{"type":"string","enum":["uploading","queued","fetching","scanning","probing","ready","deleting","rejected","failed","deleted"]},"durationSeconds":{"type":["number","null"]},"startedMinutes":{"type":["integer","null"]},"sha256":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"Artifact":{"type":"object","required":["artifactId","kind","filename","contentType","downloadUrl","downloadExpiresAt"],"properties":{"artifactId":{"type":"string"},"kind":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":["string","null"],"pattern":"^[0-9]+$","description":"Decimal byte count, serialized as a string for integer safety."},"sha256":{"type":["string","null"]},"downloadUrl":{"type":"string","format":"uri"},"downloadExpiresAt":{"type":"string","format":"date-time"}}},"Job":{"type":"object","required":["jobId","kind","status","sourceId","startedMinutes","priceUsd","artifacts"],"properties":{"jobId":{"type":"string"},"sourceId":{"type":"string"},"kind":{"type":"string","enum":["scribe","dub"]},"status":{"type":"string","enum":["invoice_creating","invoice_pending","paid","queued","processing","finalizing","ready","ready_partial","failed","needs_attention","deleted"]},"sourceLanguage":{"type":["string","null"]},"targetLanguage":{"type":["string","null"]},"startedMinutes":{"type":"integer"},"priceUsd":{"type":"number"},"amountSats":{"type":["integer","null"]},"receipt":{"type":["string","null"],"readOnly":true},"receiptAuthorization":{"type":["string","null"],"readOnly":true,"description":"Ready-to-use AgentReceipt Authorization header value."},"retryAfterSeconds":{"type":["integer","null"]},"error":{"type":["string","null"]},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/Artifact"}}}},"PaymentChallenge":{"type":"object","required":["error","code","jobId","invoice","amountSats","priceUsd","expiresAt","wwwAuthenticate"],"properties":{"error":{"type":"string","const":"Payment Required"},"code":{"type":"string","const":"PAYMENT_REQUIRED"},"jobId":{"type":"string"},"invoice":{"type":"string"},"amountSats":{"type":"integer"},"priceUsd":{"type":"number"},"expiresAt":{"type":"string","format":"date-time"},"wwwAuthenticate":{"type":"string","description":"Same L402 challenge value returned in the WWW-Authenticate header."}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}}}},"x-service-status":{"mode":"DISCOVERY_ONLY","discoveryAvailable":true,"acceptingSources":false,"acceptingJobs":false,"processingPaidJobs":false,"retryAfterSeconds":300}}