{"openapi":"3.1.0","info":{"title":"ShowBits automations","version":"1","description":"The routes for n8n, Zapier, Make and the like (docs/automations.md), in every plan: a connection's key, up to 300 requests a minute. Changes within /v1 are additive."},"servers":[{"url":"https://app.showbits.ai/api/automation/v1"}],"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"A connection's key (sbau_…) from Integrations → Automations in ShowBits. It acts in its workspace for the person who answers for the connection."}},"schemas":{"Connection":{"type":"object","properties":{"connection":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"name":{"type":"string"},"tool":{"type":"string","enum":["n8n","zapier","make","other"]},"embargoed":{"type":"boolean","description":"Sees clips and episodes before their embargo ends"}},"required":["id","name","tool","embargoed"]},"workspace":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]},"plan":{"type":"string","enum":["hobby","creator","business","enterprise","onprem"]},"responsible":{"type":["string","null"],"description":"Who answers for what the connection does (approvals are in their name)"},"limits":{"type":"object","properties":{"connections":{"type":"integer"},"requestsPerMinute":{"type":"integer"}},"required":["connections","requestsPerMinute"]}},"required":["connection","workspace","plan","responsible","limits"]},"Failure":{"type":"object","properties":{"error":{"type":"string","description":"Why, a fixed word: unauthorized, inactive, owner, notFound, embargo, stale, invalid, target, limit, tooMany"},"hint":{"type":"string","description":"unauthorized: what to fix, in words (for example the missing \"Bearer \")"},"embargoUntil":{"type":["string","null"],"format":"date-time","description":"embargo: when it ends"},"status":{"type":"string","enum":["review","approved","scheduled","published","rejected"],"description":"stale: where the clip is now"},"stage":{"type":"integer"},"stages":{"type":"integer"}},"required":["error"]},"Clip":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"episodeId":{"type":"string","description":"UUID"},"kind":{"type":"string","enum":["highlight","meme","quote"]},"title":{"type":"string"},"status":{"type":"string","enum":["review","approved","scheduled","published","rejected"]},"approval":{"type":"object","properties":{"stage":{"type":"integer"},"stages":{"type":"integer"}},"required":["stage","stages"],"description":"The step a clip in review waits for, of the workspace's steps; approving names it"},"startSec":{"type":"number"},"durationSec":{"type":"number"},"format":{"type":"string"},"embargoUntil":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"releasedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","episodeId","kind","title","status","approval","startSec","durationSec","format","embargoUntil","createdAt","releasedAt"]},"ClipDetail":{"allOf":[{"$ref":"#/components/schemas/Clip"},{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"captionTranslations":{"type":"object","additionalProperties":{"type":"string"},"description":"The caption in other languages, by language code"},"quote":{"type":["object","null"],"properties":{"said":{"type":"string"},"name":{"type":["string","null"]}},"required":["said","name"]},"episode":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"title":{"type":"string"},"language":{"type":["string","null"]}},"required":["id","title","language"]},"appUrl":{"type":"string","description":"The clip in ShowBits (for members of the workspace)"},"files":{"type":"object","properties":{"video":{"$ref":"#/components/schemas/File"},"subtitles":{"allOf":[{"$ref":"#/components/schemas/File"},{"description":"WebVTT, for a clip with burned-in subtitles"}]},"images":{"type":"object","properties":{"16x9":{"$ref":"#/components/schemas/File"},"9x16":{"$ref":"#/components/schemas/File"},"4x5":{"$ref":"#/components/schemas/File"},"1x1":{"$ref":"#/components/schemas/File"}}},"animations":{"type":"object","properties":{"9x16":{"$ref":"#/components/schemas/File"},"4x5":{"$ref":"#/components/schemas/File"}},"description":"An animated quote card's videos with the speaker's voice (MP4), once rendered"}},"required":["video","subtitles","images","animations"]}},"required":["caption","hashtags","captionTranslations","quote","episode","appUrl","files"]}]},"File":{"type":["object","null"],"properties":{"url":{"type":"string","description":"A signed link, valid for an hour"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]},"Episode":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"title":{"type":"string"},"language":{"type":["string","null"]},"durationSec":{"type":"number"},"show":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"name":{"type":"string"}},"required":["id","name"]},"embargoUntil":{"type":["string","null"],"format":"date-time"},"analysedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"clips":{"type":"object","properties":{"review":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"}},"required":["review","approved","rejected"]},"appUrl":{"type":"string"}},"required":["id","title","language","durationSec","show","embargoUntil","analysedAt","createdAt","clips","appUrl"]},"Decision":{"type":"object","properties":{"result":{"type":"string","enum":["approved","forwarded","rejected"]},"status":{"type":"string","enum":["review","approved","scheduled","published","rejected"]},"stage":{"type":"integer"},"stages":{"type":"integer"}},"required":["result","status","stage","stages"],"description":"approved: released; forwarded: now waits for the next step; rejected: sent back"},"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"UUID"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"paused":{"type":["string","null"],"enum":["manual","failing",null]},"failingSince":{"type":["string","null"],"format":"date-time"},"lastSuccessAt":{"type":["string","null"],"format":"date-time"}},"required":["id","url","events","description","createdAt","paused","failingSince","lastSuccessAt"]}},"parameters":{}},"paths":{"/me":{"get":{"tags":["Connection"],"summary":"The connection, its workspace and limits","security":[{"key":[]}],"responses":{"200":{"description":"The connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/clips":{"get":{"tags":["Clips"],"summary":"The workspace's clips, oldest first, by status and episode","description":"Clips of episodes under embargo only for a connection made to see them.","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","enum":["review","approved","scheduled","published","rejected"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"episodeId","in":"query"},{"schema":{"type":"string","maxLength":64},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Clip"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/clips/{id}":{"get":{"tags":["Clips"],"summary":"One clip with its texts and links to its files (an hour)","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The clip","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClipDetail"}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"Under embargo (embargo, with its end)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/episodes/{id}":{"get":{"tags":["Episodes"],"summary":"One episode: its show, embargo, analysis and clips","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The episode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Episode"}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"Under embargo (embargo, with its end)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/clips/{id}/approve":{"post":{"tags":["Approval"],"summary":"Approves the step a clip in review waits for","description":"In the name of the person who answers for the connection; the audit log names the connection and `by`. Only a clip in review at `stage` moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"integer","minimum":1,"maximum":10,"description":"The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on"},"comment":{"type":"string","maxLength":2000},"by":{"type":"string","maxLength":120,"description":"Who clicked, as your tool knows them; kept in the audit log as reported"}},"required":["stage"],"additionalProperties":false}}}},"responses":{"200":{"description":"What happened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"stale (the clip moved on) or embargo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/clips/{id}/reject":{"post":{"tags":["Approval"],"summary":"Sends a clip in review back","description":"In the name of the person who answers for the connection; the audit log names the connection and `by`. Only a clip in review at `stage` moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"integer","minimum":1,"maximum":10,"description":"The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on"},"comment":{"type":"string","maxLength":2000},"by":{"type":"string","maxLength":120,"description":"Who clicked, as your tool knows them; kept in the audit log as reported"}},"required":["stage"],"additionalProperties":false}}}},"responses":{"200":{"description":"What happened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"409":{"description":"stale (the clip moved on) or embargo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/hooks":{"get":{"tags":["Webhooks"],"summary":"The connection's webhooks","security":[{"key":[]}],"responses":{"200":{"description":"Its webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"]}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}},"post":{"tags":["Webhooks"],"summary":"Subscribes an address to events (the secret comes once)","description":"Events come as a POST signed like the REST API's webhooks (ShowBits-Signature: t=…,v1=HMAC-SHA256 of t.body). They name objects by id only; read them here. At most 10 webhooks per workspace, with the API's.","security":[{"key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"description":"https, reachable from the internet"},"events":{"type":"array","items":{"type":"string","enum":["clip.approved","clip.deleted","clip.forwarded","clip.rejected","clip.submitted","clip.video_ready","episode.analysed","episode.created","episode.deleted","episode.embargo_changed","episode.embargo_ended","episode.submitted"]},"minItems":1,"maxItems":12},"description":{"type":"string","maxLength":200}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Subscribed","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}},"required":["webhook","secret"]}}}},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"422":{"description":"Invalid, or an address ShowBits may not reach (target)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}},"/hooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Unsubscribes","security":[{"key":[]}],"parameters":[{"schema":{"type":"string","maxLength":64},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Gone"},"401":{"description":"No or an unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"403":{"description":"The trial has ended (inactive), or nobody answers for the connection (owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"404":{"description":"Unknown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}},"429":{"description":"Too many requests a minute (tooMany), or a limit reached (limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Failure"}}}}}}}},"webhooks":{}}