{"openapi":"3.1.0","info":{"title":"Post Editor Render API","version":"0.1.0","description":"Render social post/carousel images from a structured JSON document."},"paths":{"/api/health":{"get":{"operationId":"getApiHealth","summary":"Health check for deployment and smoke tests","responses":{"200":{"description":"API is running","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/render-schema":{"get":{"operationId":"getRenderSchema","summary":"Get the render contract and supported enum values","responses":{"200":{"description":"Render schema","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/render":{"post":{"operationId":"renderPostImages","summary":"Render one post or carousel into image data URLs","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slides"],"additionalProperties":false,"properties":{"platform":{"type":"string","enum":["tiktok-carousel","tiktok-story","instagram-post","instagram-square","instagram-story","linkedin-post","linkedin-portrait"],"default":"tiktok-carousel"},"mode":{"type":"string","enum":["single","carousel"],"default":"single"},"format":{"type":"string","enum":["png","svg"],"default":"png"},"delivery":{"type":"string","enum":["dataUrl","url","both"],"default":"dataUrl","description":"Use url for temporary hosted image URLs, dataUrl for inline base64, or both for both forms. Temporary URLs should be fetched immediately."},"brand":{"type":"string","enum":["thebar","cookpaddy","custom"],"default":"thebar"},"stepperStyle":{"type":"string","enum":["none","numeric","dots","dots-outline","bars","pills","line","minimal"],"default":"numeric"},"slides":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#000000"},"image":{"type":"string","nullable":true,"description":"HTTP(S) image URL or data:image URL used as cover background."},"textBlocks":{"type":"array","maxItems":30,"items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"},"richText":{"type":"string","description":"Optional simple HTML text. Supports b/strong, i/em, u, s/strike/del, mark, br, and span style color/background-color/text-transform."},"emoji":{"type":"string"},"size":{"type":"string","enum":["S","M","L","XL"],"default":"L"},"fontSize":{"type":"number","minimum":8,"maximum":240,"default":36},"style":{"type":"string","enum":["bold","shadow","outline","highlight"],"default":"bold"},"textColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#FFFFFF"},"highlightColor":{"type":"string","default":"#D4AF37"},"x":{"type":"number","default":50},"y":{"type":"number","default":300},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"maxWidth":{"type":"number","nullable":true},"rotation":{"type":"number","minimum":-180,"maximum":180,"default":0}}},"default":[]},"imageOverlays":{"type":"array","maxItems":30,"items":{"type":"object","required":["src"],"additionalProperties":false,"properties":{"src":{"type":"string","description":"HTTP(S) image URL or data:image URL."},"name":{"type":"string"},"x":{"type":"number","default":50},"y":{"type":"number","default":50},"width":{"type":"number","default":180},"height":{"type":"number","default":180},"rotation":{"type":"number","minimum":-180,"maximum":180,"default":0},"borderRadius":{"type":"number","minimum":0,"default":0},"cropX":{"type":"number","minimum":0,"maximum":100,"default":50},"cropY":{"type":"number","minimum":0,"maximum":100,"default":50},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","nullable":true,"description":"Optional color mask using the image alpha/luminance."},"opacity":{"type":"number","minimum":0,"maximum":1,"default":1}}},"default":[]},"counterPosition":{"type":"object","nullable":true,"properties":{"x":{"type":"number"},"y":{"type":"number"}}}}}}}},"examples":{"singlePost":{"value":{"platform":"instagram-square","mode":"single","format":"png","delivery":"url","brand":"thebar","slides":[{"backgroundColor":"#111111","textBlocks":[{"text":"Curl render proof","fontSize":44,"style":"highlight","textColor":"#000000","highlightColor":"#D4AF37","x":44,"y":190,"maxWidth":320}]}]}},"carousel":{"value":{"platform":"instagram-post","mode":"carousel","format":"png","delivery":"url","brand":"thebar","stepperStyle":"numeric","slides":[{"backgroundColor":"#000000","textBlocks":[{"text":"5 content ideas for tonight","fontSize":48,"style":"bold","textColor":"#FFFFFF","x":42,"y":120,"maxWidth":330}]},{"backgroundColor":"#D4AF37","textBlocks":[{"text":"Turn one insight into a carousel","fontSize":42,"style":"outline","textColor":"#FFFFFF","x":42,"y":160,"maxWidth":330}]}]}},"remoteImage":{"value":{"platform":"instagram-square","mode":"single","format":"png","delivery":"url","slides":[{"image":"https://placehold.co/128x128/png","textBlocks":[{"text":"Remote image background","fontSize":40,"style":"bold","textColor":"#FFFFFF","x":44,"y":120,"maxWidth":320}]}]}}}}}},"responses":{"200":{"description":"Rendered image outputs","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"format":{"type":"string","enum":["png","svg"]},"delivery":{"type":"string","enum":["dataUrl","url","both"]},"platform":{"type":"string"},"mode":{"type":"string"},"slideCount":{"type":"number"},"images":{"type":"array","items":{"type":"object","properties":{"slide":{"type":"number"},"mimeType":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"url":{"type":"string","description":"Returned when delivery is url or both."},"dataUrl":{"type":"string","description":"Returned when delivery is dataUrl or both."},"svg":{"type":"string","description":"Only returned when format is svg."}}}}}}}}},"400":{"description":"Invalid render request"}}}},"/api/render.png":{"post":{"operationId":"renderPostPng","summary":"Render a single slide directly as image/png","parameters":[{"name":"slide","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"1-based slide number to return. Useful for carousel requests."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slides"],"additionalProperties":false,"properties":{"platform":{"type":"string","enum":["tiktok-carousel","tiktok-story","instagram-post","instagram-square","instagram-story","linkedin-post","linkedin-portrait"],"default":"tiktok-carousel"},"mode":{"type":"string","enum":["single","carousel"],"default":"single"},"format":{"type":"string","enum":["png","svg"],"default":"png"},"delivery":{"type":"string","enum":["dataUrl","url","both"],"default":"dataUrl","description":"Use url for temporary hosted image URLs, dataUrl for inline base64, or both for both forms. Temporary URLs should be fetched immediately."},"brand":{"type":"string","enum":["thebar","cookpaddy","custom"],"default":"thebar"},"stepperStyle":{"type":"string","enum":["none","numeric","dots","dots-outline","bars","pills","line","minimal"],"default":"numeric"},"slides":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"backgroundColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#000000"},"image":{"type":"string","nullable":true,"description":"HTTP(S) image URL or data:image URL used as cover background."},"textBlocks":{"type":"array","maxItems":30,"items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string"},"richText":{"type":"string","description":"Optional simple HTML text. Supports b/strong, i/em, u, s/strike/del, mark, br, and span style color/background-color/text-transform."},"emoji":{"type":"string"},"size":{"type":"string","enum":["S","M","L","XL"],"default":"L"},"fontSize":{"type":"number","minimum":8,"maximum":240,"default":36},"style":{"type":"string","enum":["bold","shadow","outline","highlight"],"default":"bold"},"textColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#FFFFFF"},"highlightColor":{"type":"string","default":"#D4AF37"},"x":{"type":"number","default":50},"y":{"type":"number","default":300},"width":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"maxWidth":{"type":"number","nullable":true},"rotation":{"type":"number","minimum":-180,"maximum":180,"default":0}}},"default":[]},"imageOverlays":{"type":"array","maxItems":30,"items":{"type":"object","required":["src"],"additionalProperties":false,"properties":{"src":{"type":"string","description":"HTTP(S) image URL or data:image URL."},"name":{"type":"string"},"x":{"type":"number","default":50},"y":{"type":"number","default":50},"width":{"type":"number","default":180},"height":{"type":"number","default":180},"rotation":{"type":"number","minimum":-180,"maximum":180,"default":0},"borderRadius":{"type":"number","minimum":0,"default":0},"cropX":{"type":"number","minimum":0,"maximum":100,"default":50},"cropY":{"type":"number","minimum":0,"maximum":100,"default":50},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","nullable":true,"description":"Optional color mask using the image alpha/luminance."},"opacity":{"type":"number","minimum":0,"maximum":1,"default":1}}},"default":[]},"counterPosition":{"type":"object","nullable":true,"properties":{"x":{"type":"number"},"y":{"type":"number"}}}}}}}},"examples":{"singlePost":{"value":{"platform":"instagram-square","mode":"single","format":"png","delivery":"url","brand":"thebar","slides":[{"backgroundColor":"#111111","textBlocks":[{"text":"Curl render proof","fontSize":44,"style":"highlight","textColor":"#000000","highlightColor":"#D4AF37","x":44,"y":190,"maxWidth":320}]}]}},"carousel":{"value":{"platform":"instagram-post","mode":"carousel","format":"png","delivery":"url","brand":"thebar","stepperStyle":"numeric","slides":[{"backgroundColor":"#000000","textBlocks":[{"text":"5 content ideas for tonight","fontSize":48,"style":"bold","textColor":"#FFFFFF","x":42,"y":120,"maxWidth":330}]},{"backgroundColor":"#D4AF37","textBlocks":[{"text":"Turn one insight into a carousel","fontSize":42,"style":"outline","textColor":"#FFFFFF","x":42,"y":160,"maxWidth":330}]}]}},"remoteImage":{"value":{"platform":"instagram-square","mode":"single","format":"png","delivery":"url","slides":[{"image":"https://placehold.co/128x128/png","textBlocks":[{"text":"Remote image background","fontSize":40,"style":"bold","textColor":"#FFFFFF","x":44,"y":120,"maxWidth":320}]}]}}}}}},"responses":{"200":{"description":"Rendered PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid render request"}}}},"/api/assets/unsplash/search":{"get":{"operationId":"searchUnsplashAssets","summary":"Search Unsplash images for backgrounds or overlays","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","default":"social media background"}},{"name":"target","in":"query","required":false,"schema":{"type":"string","enum":["background","overlay"],"default":"background"},"description":"Helps clients choose whether the result will be used as slide.image or imageOverlays[].src."},{"name":"orientation","in":"query","required":false,"schema":{"type":"string","enum":["landscape","portrait","squarish"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":12}}],"responses":{"200":{"description":"Search results. Use result.renderUrl in render requests."}}}},"/api/assets/unsplash/track-download":{"post":{"operationId":"trackUnsplashDownload","summary":"Track an Unsplash download after using an asset","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["downloadLocation"],"properties":{"downloadLocation":{"type":"string","description":"The attribution.downloadLocation returned by /api/assets/unsplash/search."}}}}}},"responses":{"200":{"description":"Download tracked"},"400":{"description":"Invalid download URL"}}}},"/api/assets/hugeicons/search":{"get":{"operationId":"searchHugeiconsAssets","summary":"Search Hugeicons SVG assets for overlays","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":80,"default":40}}],"responses":{"200":{"description":"Icon results. Use result.renderUrl in imageOverlays[].src."}}}}}}