{"openapi":"3.1.0","info":{"title":"Duply API","version":"2.0.0","description":"Create and monitor scalable image and video renders. Legacy v1 contracts remain available for existing integrations."},"servers":[{"url":"https://api.duply.co/v2"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"security":[],"operationId":"getHealth","summary":"Check API availability","responses":{"200":{"description":"API is available"}}}},"/templates":{"get":{"operationId":"listTemplates","summary":"List templates","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Template page"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTemplate","summary":"Create a template with its first variant","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplate"}}}},"responses":{"201":{"description":"Template created"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid template request"}}}},"/templates/{templateId}":{"get":{"operationId":"getTemplate","summary":"Get a template and its variants","parameters":[{"in":"path","name":"templateId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateTemplate","summary":"Update template metadata and publication state","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplate"}}}},"responses":{"200":{"description":"Template updated"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid template update"}}},"delete":{"operationId":"archiveTemplate","summary":"Archive a template","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"responses":{"200":{"description":"Template archived"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/templates/{templateId}/variants":{"post":{"operationId":"createTemplateVariant","summary":"Create a template variant","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariant"}}}},"responses":{"201":{"description":"Variant created"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid variant request"}}}},"/templates/{templateId}/variants/{variantId}":{"patch":{"operationId":"updateTemplateVariant","summary":"Update a variant document or metadata","parameters":[{"$ref":"#/components/parameters/TemplateId"},{"in":"path","name":"variantId","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVariant"}}}},"responses":{"200":{"description":"Variant updated"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid variant update"}}}},"/renders":{"get":{"operationId":"listRenders","summary":"List render jobs","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"in":"query","name":"status","schema":{"type":"string","enum":["queued","running","completed","failed"]}},{"in":"query","name":"kind","schema":{"type":"string","enum":["image","video"]}}],"responses":{"200":{"description":"Render page"}}},"post":{"operationId":"createRender","summary":"Create an idempotent render job","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRender"}}}},"responses":{"202":{"description":"Render accepted"},"402":{"description":"Insufficient credits"},"422":{"description":"Invalid render request"},"429":{"description":"Render rate limit exceeded"}}}},"/renders/{renderId}":{"get":{"operationId":"getRender","summary":"Get render status and generated files","parameters":[{"in":"path","name":"renderId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Render job"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get billing-period and top-up usage","responses":{"200":{"description":"Workspace usage"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"parameters":{"TemplateId":{"in":"path","name":"templateId","required":true,"schema":{"type":"string"}},"Limit":{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"Cursor":{"in":"query","name":"cursor","schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"API key is missing or invalid","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"Forbidden":{"description":"API key does not have the required scope","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"NotFound":{"description":"Resource was not found","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}},"schemas":{"Meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","format":"uuid"},"nextCursor":{"type":["string","null"]}}},"CreateRender":{"type":"object","properties":{"templateId":{"type":"string"},"variantId":{"type":"string"},"variantName":{"type":"string"},"kind":{"type":"string","enum":["image","video"],"default":"image"},"output":{"type":"object","properties":{"format":{"type":"string","enum":["png","jpeg","mp4"]}}},"durationSeconds":{"type":"number","minimum":0.5,"maximum":30,"description":"Duration for a template-based MP4 render."},"variables":{"type":"object","additionalProperties":true},"batch":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object"}},"blueprint":{"type":"object","description":"Optional animated VideoBlueprint. For a stored template video, send kind=video with templateId instead."},"metadata":{"type":"object"}}},"CreateTemplate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"type":{"type":"string","enum":["image","video"]},"width":{"type":"integer","minimum":1,"maximum":10000},"height":{"type":"integer","minimum":1,"maximum":10000},"background":{"type":"string"},"variant":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"document":{"type":"object","additionalProperties":true}}},"metadata":{"type":"object","additionalProperties":true}}},"UpdateTemplate":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","maxLength":200},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","published"]},"width":{"type":"integer","minimum":1,"maximum":10000},"height":{"type":"integer","minimum":1,"maximum":10000},"background":{"type":["string","null"]},"thumbnailUrl":{"type":["string","null"],"format":"uri"},"isPublic":{"type":"boolean"},"isArchived":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true}}},"CreateVariant":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"document":{"type":"object","additionalProperties":true},"width":{"type":"integer","minimum":1,"maximum":10000},"height":{"type":"integer","minimum":1,"maximum":10000},"thumbnailUrl":{"type":"string","format":"uri"},"sortOrder":{"type":"integer","minimum":0}}},"UpdateVariant":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","maxLength":200},"document":{"type":"object","additionalProperties":true},"width":{"type":["integer","null"],"minimum":1,"maximum":10000},"height":{"type":["integer","null"],"minimum":1,"maximum":10000},"thumbnailUrl":{"type":["string","null"],"format":"uri"},"sortOrder":{"type":"integer","minimum":0}}}}}}