{"openapi":"3.1.0","info":{"title":"The Scribble Thing Agent API","description":"Create a scribe animation, poll its status, download the watermarked preview, optionally unlock the clean video, or delete the session. Session files expire within 24 hours.","version":"1.0.0"},"paths":{"/agent/v1":{"get":{"tags":["agent"],"summary":"Discover the Agent API","description":"Return stable documentation, policy, and schema links for agents.","operationId":"discover_agent_api","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Discover Agent Api"}}}}}}},"/agent/v1/animations":{"post":{"tags":["agent"],"summary":"Create a scribe animation","description":"Upload PNG or JPEG line art and optional drawing-order instructions. Returns a per-animation bearer capability and polling URLs.","operationId":"create_scribe_animation","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200,"description":"Unique non-personal key for safe retries.","title":"Idempotency-Key"},"description":"Unique non-personal key for safe retries."},{"name":"X-Agent-Installation-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":8,"maxLength":200},{"type":"null"}],"description":"Stable non-personal installation identifier; stored as a hash.","title":"X-Agent-Installation-Id"},"description":"Stable non-personal installation identifier; stored as a hash."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_scribe_animation"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateResponse"}}}},"200":{"description":"Idempotent replay of the original create request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateResponse"}}}},"400":{"description":"Invalid image, consent, or terms version."},"409":{"description":"Idempotency key reused for different input."},"429":{"description":"Generation quota reached."},"503":{"description":"Capacity or temporary storage failure."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/animations/{animation_id}":{"get":{"tags":["agent"],"summary":"Get animation status","description":"Poll queued or running work and discover available downloads.","operationId":"get_scribe_animation","security":[{"AnimationCapability":[]}],"parameters":[{"name":"animation_id","in":"path","required":true,"schema":{"type":"string","title":"Animation Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAnimationResponse"}}}},"401":{"description":"Bearer capability missing or malformed."},"404":{"description":"Animation and capability pairing not found."},"410":{"description":"Animation expired or was deleted."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["agent"],"summary":"Delete an animation","description":"Immediately delete the session record and all session files.","operationId":"delete_scribe_animation","security":[{"AnimationCapability":[]}],"parameters":[{"name":"animation_id","in":"path","required":true,"schema":{"type":"string","title":"Animation Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Bearer capability missing or malformed."},"404":{"description":"Animation and capability pairing not found."},"410":{"description":"Animation already expired or was deleted."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/animations/{animation_id}/preview":{"get":{"tags":["agent"],"summary":"Download the watermarked preview","description":"Download the completed free watermarked MP4.","operationId":"download_scribe_preview","security":[{"AnimationCapability":[]}],"parameters":[{"name":"animation_id","in":"path","required":true,"schema":{"type":"string","title":"Animation Id"}}],"responses":{"200":{"description":"Watermarked MP4 video","content":{"application/json":{"schema":{}},"video/mp4":{}}},"307":{"description":"Short-lived redirect to private object storage."},"409":{"description":"Animation is not complete."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/animations/{animation_id}/clean":{"get":{"tags":["agent"],"summary":"Download the clean video","description":"Download the completed MP4 after a code unlocks this animation.","operationId":"download_clean_scribe_animation","security":[{"AnimationCapability":[]}],"parameters":[{"name":"animation_id","in":"path","required":true,"schema":{"type":"string","title":"Animation Id"}}],"responses":{"200":{"description":"Clean MP4 video","content":{"application/json":{"schema":{}},"video/mp4":{}}},"307":{"description":"Short-lived redirect to private object storage."},"403":{"description":"Animation has not been unlocked."},"409":{"description":"Animation is not complete."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agent/v1/animations/{animation_id}/unlock":{"post":{"tags":["agent"],"summary":"Redeem an unlock code","description":"Optionally redeem a user-supplied single-use code. Browser handoff via manage_url is recommended when the user still needs to purchase one.","operationId":"unlock_scribe_animation","security":[{"AnimationCapability":[]}],"parameters":[{"name":"animation_id","in":"path","required":true,"schema":{"type":"string","title":"Animation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUnlockRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAnimationResponse"}}}},"400":{"description":"Code invalid, expired, disabled, or already used."},"429":{"description":"Too many failed unlock attempts."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentAnimationResponse":{"properties":{"animation_id":{"type":"string","title":"Animation Id","description":"Canonical UUID for this animation."},"status":{"type":"string","enum":["queued","running","completed","failed"],"title":"Status","description":"Current asynchronous job state."},"stage":{"type":"string","title":"Stage","description":"Short user-facing description of current work."},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Approximate percent complete."},"error":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"type":"string","title":"Expires At"},"seconds_remaining":{"type":"integer","title":"Seconds Remaining"},"retention_hours":{"type":"integer","title":"Retention Hours"},"terms_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms Version"},"unlocked":{"type":"boolean","title":"Unlocked"},"preview_download_available":{"type":"boolean","title":"Preview Download Available"},"clean_download_available":{"type":"boolean","title":"Clean Download Available"},"status_url":{"type":"string","title":"Status Url"},"preview_url":{"type":"string","title":"Preview Url"},"clean_url":{"type":"string","title":"Clean Url"},"manage_url":{"type":"string","title":"Manage Url","description":"Private browser handoff URL for user review and unlock."},"purchase_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purchase Url"},"unlock":{"$ref":"#/components/schemas/AgentUnlockDetails"}},"type":"object","required":["animation_id","status","stage","progress","error","created_at","expires_at","seconds_remaining","retention_hours","terms_version","unlocked","preview_download_available","clean_download_available","status_url","preview_url","clean_url","manage_url","purchase_url","unlock"],"title":"AgentAnimationResponse"},"AgentCreateResponse":{"properties":{"animation_id":{"type":"string","title":"Animation Id","description":"Canonical UUID for this animation."},"status":{"type":"string","enum":["queued","running","completed","failed"],"title":"Status","description":"Current asynchronous job state."},"stage":{"type":"string","title":"Stage","description":"Short user-facing description of current work."},"progress":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Progress","description":"Approximate percent complete."},"error":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"},"expires_at":{"type":"string","title":"Expires At"},"seconds_remaining":{"type":"integer","title":"Seconds Remaining"},"retention_hours":{"type":"integer","title":"Retention Hours"},"terms_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms Version"},"unlocked":{"type":"boolean","title":"Unlocked"},"preview_download_available":{"type":"boolean","title":"Preview Download Available"},"clean_download_available":{"type":"boolean","title":"Clean Download Available"},"status_url":{"type":"string","title":"Status Url"},"preview_url":{"type":"string","title":"Preview Url"},"clean_url":{"type":"string","title":"Clean Url"},"manage_url":{"type":"string","title":"Manage Url","description":"Private browser handoff URL for user review and unlock."},"purchase_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purchase Url"},"unlock":{"$ref":"#/components/schemas/AgentUnlockDetails"},"access_token":{"type":"string","title":"Access Token","description":"Secret bearer capability scoped to this animation only."},"token_type":{"type":"string","const":"Bearer","title":"Token Type"},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay"}},"type":"object","required":["animation_id","status","stage","progress","error","created_at","expires_at","seconds_remaining","retention_hours","terms_version","unlocked","preview_download_available","clean_download_available","status_url","preview_url","clean_url","manage_url","purchase_url","unlock","access_token","token_type","idempotent_replay"],"title":"AgentCreateResponse"},"AgentUnlockDetails":{"properties":{"state":{"type":"string","enum":["watermarked","unlocked"],"title":"State"},"instructions":{"type":"string","title":"Instructions"},"endpoint":{"type":"string","title":"Endpoint"},"purchase_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purchase Url"}},"type":"object","required":["state","instructions","endpoint","purchase_url"],"title":"AgentUnlockDetails"},"AgentUnlockRequest":{"properties":{"code":{"type":"string","maxLength":100,"minLength":1,"title":"Code","description":"A single-use unlock code supplied by the user.","examples":["UNLOCK-XXXX-XXXX-XXXX"]}},"type":"object","required":["code"],"title":"AgentUnlockRequest"},"Body_create_scribe_animation":{"properties":{"image":{"type":"string","contentMediaType":"application/octet-stream","title":"Image","description":"PNG or JPEG artwork bytes."},"order_text":{"type":"string","maxLength":2000,"title":"Order Text","description":"Optional natural-language component drawing order.","default":""},"show_hand":{"type":"boolean","title":"Show Hand","description":"Whether a drawing hand follows the reveal.","default":false},"speed":{"type":"string","enum":["slow","normal","fast"],"title":"Speed","description":"Target animation speed preset.","default":"normal"},"accept_retention":{"type":"boolean","title":"Accept Retention","description":"Must acknowledge 24-hour file retention.","default":false},"accept_terms":{"type":"boolean","title":"Accept Terms","description":"Must accept the current Terms of Use.","default":false},"terms_version":{"type":"string","maxLength":40,"minLength":1,"title":"Terms Version","description":"Accepted terms version."},"client_name":{"type":"string","maxLength":80,"minLength":1,"title":"Client Name","description":"Non-personal client label."},"client_version":{"type":"string","maxLength":40,"title":"Client Version","description":"Calling client version.","default":""},"marketplace":{"type":"string","maxLength":80,"title":"Marketplace","description":"Optional integration source.","default":""}},"type":"object","required":["image","terms_version","client_name"],"title":"Body_create_scribe_animation"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"AnimationCapability":{"type":"http","description":"The per-animation bearer capability returned by create.","scheme":"bearer"}}},"servers":[{"url":"https://scribble.boringstuff.club"}],"externalDocs":{"description":"Agent API guide","url":"https://scribble.boringstuff.club/docs/agent-api"},"x-session-retention-hours":24}