{"openapi":"3.0.3","info":{"title":"RenderSnap API","version":"1.0.0","description":"API-first video rendering and automation platform. Send `Authorization: Bearer <token>` on every request, where the token is either a session token or a workspace API key."},"servers":[{"url":"/api/v1","description":"Same-origin production API"}],"tags":[{"name":"Auth"},{"name":"API Keys"},{"name":"Workspace"},{"name":"Team"},{"name":"Projects"},{"name":"Assets"},{"name":"Templates"},{"name":"Renders"},{"name":"Batch Renders"}],"components":{"securitySchemes":{"AuthorizationHeader":{"type":"apiKey","in":"header","name":"Authorization","description":"Enter the full header value, for example `Bearer <session_token>` or `Bearer rs_your_workspace_api_key`."}},"schemas":{"CounterConfig":{"type":"object","description":"A number counting from `from` to `to`.","required":["template","style","color","accentColor","trackColor","textColor","easing","entrance","animSeconds","from","to","decimals","prefix","suffix","separator","label"],"properties":{"template":{"type":"string","enum":["counter"]},"style":{"type":"string","enum":["classic","neon","odometer","flip"]},"color":{"type":"string","description":"#rrggbb. Digits, bar fill, ring."},"accentColor":{"type":"string","description":"#rrggbb. Glow, gradient end, final-seconds flash."},"trackColor":{"type":"string","description":"#rrggbb. Unfilled track and card faces."},"textColor":{"type":"string","description":"#rrggbb. Labels."},"easing":{"type":"string","enum":["linear","easeOut","easeInOut","bounce","elastic"]},"entrance":{"type":"string","enum":["none","fade","pop","slideUp"]},"animSeconds":{"type":"number","description":"Seconds the value takes to reach its end, then holds. Ignored by countdowns."},"from":{"type":"number"},"to":{"type":"number"},"decimals":{"type":"integer","minimum":0,"maximum":3},"prefix":{"type":"string"},"suffix":{"type":"string"},"separator":{"type":"boolean","description":"Group thousands (12,500)."},"label":{"type":"string","description":"Line under the number; empty for none."}}},"CountdownConfig":{"type":"object","description":"A clock counting down to zero.","required":["template","style","color","accentColor","trackColor","textColor","easing","entrance","animSeconds","seconds","label"],"properties":{"template":{"type":"string","enum":["countdown"]},"style":{"type":"string","enum":["digital","ring","flip"]},"color":{"type":"string","description":"#rrggbb. Digits, bar fill, ring."},"accentColor":{"type":"string","description":"#rrggbb. Glow, gradient end, final-seconds flash."},"trackColor":{"type":"string","description":"#rrggbb. Unfilled track and card faces."},"textColor":{"type":"string","description":"#rrggbb. Labels."},"easing":{"type":"string","enum":["linear","easeOut","easeInOut","bounce","elastic"]},"entrance":{"type":"string","enum":["none","fade","pop","slideUp"]},"animSeconds":{"type":"number","description":"Seconds the value takes to reach its end, then holds. Ignored by countdowns."},"seconds":{"type":"number","minimum":1,"maximum":5999,"description":"Counts down to zero in real time."},"label":{"type":"string"}}},"ProgressConfig":{"type":"object","description":"A bar or ring filling from `from`% to `to`%.","required":["template","style","color","accentColor","trackColor","textColor","easing","entrance","animSeconds","from","to","label","showPercent","segments"],"properties":{"template":{"type":"string","enum":["progress"]},"style":{"type":"string","enum":["linear","gradient","segmented","ring"]},"color":{"type":"string","description":"#rrggbb. Digits, bar fill, ring."},"accentColor":{"type":"string","description":"#rrggbb. Glow, gradient end, final-seconds flash."},"trackColor":{"type":"string","description":"#rrggbb. Unfilled track and card faces."},"textColor":{"type":"string","description":"#rrggbb. Labels."},"easing":{"type":"string","enum":["linear","easeOut","easeInOut","bounce","elastic"]},"entrance":{"type":"string","enum":["none","fade","pop","slideUp"]},"animSeconds":{"type":"number","description":"Seconds the value takes to reach its end, then holds. Ignored by countdowns."},"from":{"type":"number","minimum":0,"maximum":100},"to":{"type":"number","minimum":0,"maximum":100},"label":{"type":"string"},"showPercent":{"type":"boolean"},"segments":{"type":"integer","minimum":3,"maximum":40,"description":"Blocks in the segmented style."}}},"MotionItem":{"type":"object","description":"An animated counter, countdown or progress bar. Lives on a track with kind \"motion\".","required":["id","kind","name","start","duration","x","y","w","h","motion"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["motion"]},"name":{"type":"string"},"start":{"type":"number","description":"Seconds on the timeline."},"duration":{"type":"number","description":"Seconds on screen."},"x":{"type":"number","description":"Top-left corner, 0–1 of canvas width."},"y":{"type":"number","description":"Top-left corner, 0–1 of canvas height."},"w":{"type":"number","description":"Box width, 0–1 of canvas width."},"h":{"type":"number","description":"Box height, 0–1 of canvas height."},"opacity":{"type":"number","minimum":0,"maximum":1},"motion":{"oneOf":[{"$ref":"#/components/schemas/CounterConfig"},{"$ref":"#/components/schemas/CountdownConfig"},{"$ref":"#/components/schemas/ProgressConfig"}],"discriminator":{"propertyName":"template"}}}}}},"security":[{"AuthorizationHeader":[]}],"paths":{"/users/me":{"get":{"tags":["Auth"],"summary":"Get the authenticated user profile","description":"Also acts as a safe provisioning trigger for first login.","responses":{"200":{"description":"Current user profile returned."}}}},"/api-keys":{"get":{"tags":["API Keys"],"summary":"List active workspace API keys","responses":{"200":{"description":"Workspace API keys returned."}}},"post":{"tags":["API Keys"],"summary":"Create a scoped workspace API key","description":"Requires an authenticated user session with `api_keys:create` permission. The raw secret is only returned once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"example":{"name":"production-worker","scopes":["projects:read","assets:read","assets:upload","renders:create","renders:read"]}}}},"responses":{"201":{"description":"API key created and secret returned once."}}}},"/api-keys/{id}":{"delete":{"tags":["API Keys"],"summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked."}}}},"/workspaces/me":{"get":{"tags":["Workspace"],"summary":"Get active workspace details","responses":{"200":{"description":"Workspace details and live storage usage returned."}}},"patch":{"tags":["Workspace"],"summary":"Update workspace name or slug","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Workspace updated."}}}},"/workspaces/me/usage":{"get":{"tags":["Workspace"],"summary":"Get API usage and recent audit activity","responses":{"200":{"description":"Usage, render counts, and recent logs returned."}}}},"/workspaces/me/members":{"get":{"tags":["Team"],"summary":"List workspace members","responses":{"200":{"description":"Workspace members returned."}}}},"/workspaces/me/members/{uid}":{"patch":{"tags":["Team"],"summary":"Update a member role","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["admin","editor","viewer","billing_manager","api_user"]}}}}}},"responses":{"200":{"description":"Member role updated."}}},"delete":{"tags":["Team"],"summary":"Remove a workspace member","parameters":[{"name":"uid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Member removed."}}}},"/workspaces/me/invites":{"get":{"tags":["Team"],"summary":"List pending workspace invites","responses":{"200":{"description":"Pending invites returned."}}},"post":{"tags":["Team"],"summary":"Create and send a workspace invite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","role"],"properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","editor","viewer","billing_manager","api_user"]}}}}}},"responses":{"201":{"description":"Invite created and email queued."}}}},"/workspaces/me/invites/{inviteId}":{"delete":{"tags":["Team"],"summary":"Revoke a pending invite","parameters":[{"name":"inviteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invite revoked."}}}},"/projects":{"get":{"tags":["Projects"],"summary":"List workspace projects","responses":{"200":{"description":"Paginated project summaries returned."}},"parameters":[{"name":"standalone","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, leaves out projects that belong to a collection (audiobook chapters, podcast episodes)."},{"name":"maker","in":"query","required":false,"description":"Only videos made with this video maker (newest first, archived left out, not paginated). A video opened in the editor stops counting as a maker video.","schema":{"type":"string","enum":["audiogram","motion","holiday"]}}]},"post":{"tags":["Projects"],"summary":"Create a project","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Follower counter"},"templateId":{"type":"string"},"timelineJson":{"type":"string","description":"The timeline as a JSON string: settings (width, height, fps, backgroundColor) and tracks. The example renders an animated counter; see MotionItem and the Motion graphics guide in the docs.","example":"{\"settings\":{\"width\":1920,\"height\":1080,\"fps\":30,\"backgroundColor\":\"#100c1f\"},\"duration\":5,\"tracks\":[{\"id\":\"track-1\",\"kind\":\"motion\",\"items\":[{\"id\":\"counter-1\",\"kind\":\"motion\",\"name\":\"Follower count\",\"start\":0,\"duration\":5,\"x\":0.219,\"y\":0.32,\"w\":0.563,\"h\":0.36,\"opacity\":1,\"motion\":{\"color\":\"#ffffff\",\"accentColor\":\"#7b5cff\",\"trackColor\":\"#26263a\",\"textColor\":\"#d4d4e0\",\"easing\":\"easeOut\",\"entrance\":\"pop\",\"animSeconds\":2.5,\"template\":\"counter\",\"style\":\"classic\",\"from\":0,\"to\":12500,\"decimals\":0,\"prefix\":\"\",\"suffix\":\"\",\"separator\":true,\"label\":\"Followers\"}}]}]}"},"durationSeconds":{"type":"integer","example":5,"description":"Video length in seconds. Render minutes are counted from it."},"makerId":{"type":"string","enum":["audiogram","motion","holiday"],"description":"Set by a video maker that built timelineJson. The project is listed like any other but is meant to be reopened in that maker; opening it in the editor clears makerId.","example":null},"editorMode":{"type":"string","enum":["simple","advanced"],"default":"advanced","description":"\"simple\" opens the project in the one-lane editor used on phones: videos and images play back to back with no overlap, and there is at most one audio clip. Without a timelineJson or templateId, a simple project starts at 1080×1920 (portrait). Leaving simple is one-way (PATCH editorMode \"advanced\")."}}}}}},"responses":{"201":{"description":"Project created."}}}},"/projects/{id}":{"get":{"tags":["Projects"],"summary":"Get a project with timeline JSON","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project returned."}}},"patch":{"tags":["Projects"],"summary":"Update project metadata or timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"editorMode":{"type":"string","enum":["advanced"],"description":"Move a simple project to the full multi-track editor. One-way: a project cannot be set back to simple."}}}}}},"responses":{"200":{"description":"Project updated."}}},"delete":{"tags":["Projects"],"summary":"Archive or permanently delete a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"permanent","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Project archived or deleted."}}}},"/collections":{"get":{"tags":["Projects"],"summary":"List collections (audiobooks, podcasts) with member counts","responses":{"200":{"description":"Collection summaries returned."}}}},"/collections/{id}":{"get":{"tags":["Projects"],"summary":"Get a collection with its projects in order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection and its projects returned."},"404":{"description":"Collection not found."}}}},"/collections/{id}/renders":{"post":{"tags":["Projects"],"summary":"Render every chapter of a collection, two at a time","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["all","unrendered"],"default":"unrendered"},"resolution":{"type":"string","enum":["720p","1080p","4K"],"default":"1080p"}}}}}},"responses":{"200":{"description":"Render run started."},"402":{"description":"Not enough render minutes left."},"409":{"description":"A render run is already in progress."}}},"patch":{"tags":["Projects"],"summary":"Stop a collection's render run, or retry its failed chapters","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["stop","retry"]}}}}}},"responses":{"200":{"description":"Render run updated."}}}},"/collections/{id}/design":{"post":{"tags":["Projects"],"summary":"Apply one chapter's design, or a layout / saved template, to a collection's chapters","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["sourceProjectId"],"properties":{"sourceProjectId":{"type":"string","description":"Copy this chapter's design to every other chapter."}}},{"type":"object","required":["layout"],"properties":{"layout":{"oneOf":[{"type":"object","required":["kind","id"],"properties":{"kind":{"type":"string","enum":["builtIn"]},"id":{"type":"string","enum":["classic","audiogram","vertical"]}}},{"type":"object","required":["kind","templateId"],"properties":{"kind":{"type":"string","enum":["template"]},"templateId":{"type":"string"}}}]}}}]}}}},"responses":{"200":{"description":"Chapters updated; skipped chapters listed with a reason."}}},"delete":{"tags":["Projects"],"summary":"Undo the last design copy (chapters edited since are left alone)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chapters restored."},"404":{"description":"Nothing to undo."}}}},"/layouts":{"get":{"tags":["Projects"],"summary":"Episode layouts: built-in layouts and saved templates usable for a collection's chapters","responses":{"200":{"description":"Layout options returned."}}}},"/assets":{"get":{"tags":["Assets"],"summary":"List workspace assets","responses":{"200":{"description":"Paginated assets returned."}}},"post":{"tags":["Assets"],"summary":"Create an asset upload token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","mimeType","sizeBytes"],"properties":{"name":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer"},"projectId":{"type":"string"}}}}}},"responses":{"201":{"description":"Asset upload URL returned."}}}},"/assets/{id}":{"get":{"tags":["Assets"],"summary":"Get asset metadata","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Asset returned."}}},"patch":{"tags":["Assets"],"summary":"Update asset name, tags, or status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Asset updated."}}},"delete":{"tags":["Assets"],"summary":"Delete an asset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Asset deleted."}}}},"/templates":{"get":{"tags":["Templates"],"summary":"List public and workspace templates","responses":{"200":{"description":"Templates returned."}}},"post":{"tags":["Templates"],"summary":"Create a workspace template","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","category","timelineJson"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"timelineJson":{"type":"string"},"isPublic":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Template created."}}}},"/templates/{id}":{"get":{"tags":["Templates"],"summary":"Get a template","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template returned."}}},"delete":{"tags":["Templates"],"summary":"Delete a workspace template","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template deleted."}}}},"/renders":{"get":{"tags":["Renders"],"summary":"List render jobs","responses":{"200":{"description":"Paginated render jobs returned."}}},"post":{"tags":["Renders"],"summary":"Submit a render job","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId"],"properties":{"projectId":{"type":"string"},"resolution":{"type":"string","enum":["720p","1080p","4K"]},"format":{"type":"string","enum":["mp4","webm","gif","mp3","mov","mkv","avi","wav","aac","quality-check"]},"fps":{"type":"integer"},"quality":{"type":"integer"},"burnSubtitles":{"type":"boolean"},"versionId":{"type":"string"},"webhookUrl":{"type":"string","format":"uri"}}}}}},"callbacks":{"renderWebhook":{"{$request.body#/webhookUrl}":{"post":{"summary":"Signed render completion webhook","requestBody":{"required":true,"content":{"application/json":{"example":{"event":"render.done","renderJobId":"rnd_demo_001","projectId":"proj_demo_001","workspaceId":"ws_demo_001","status":"done","outputUrl":"https://rendersnap.io/api/v1/renders/rnd_demo_001/content","durationSeconds":42,"completedAt":"2026-06-18T09:41:00Z"}}}},"responses":{"200":{"description":"Client acknowledges webhook receipt."}}}}}},"responses":{"202":{"description":"Render job queued."}}}},"/renders/{id}":{"get":{"tags":["Renders"],"summary":"Get a render job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Render job returned."}}},"delete":{"tags":["Renders"],"summary":"Cancel a queued or processing render","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Render job cancelled."}}}},"/renders/batch":{"get":{"tags":["Batch Renders"],"summary":"List batch render jobs","responses":{"200":{"description":"Paginated batch renders returned."}}},"post":{"tags":["Batch Renders"],"summary":"Submit a multi-format batch render","description":"Fans a single project out into multiple social format renders. Supports the same `webhookUrl` field as single renders.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","formats"],"properties":{"projectId":{"type":"string"},"formats":{"type":"array","items":{"type":"string","enum":["youtube","tiktok","instagram_square","instagram_story","twitter","linkedin"]}},"resolution":{"type":"string","enum":["720p","1080p","4K"]},"format":{"type":"string","enum":["mp4","webm","gif","mp3"]},"fps":{"type":"integer"},"quality":{"type":"integer"},"burnSubtitles":{"type":"boolean"},"webhookUrl":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Batch render queued."}}}},"/renders/batch/{id}":{"get":{"tags":["Batch Renders"],"summary":"Get a batch render job","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Batch render detail returned."}}}}}}