{ "openapi": "3.1.0", "info": { "title": "Abni API", "version": "1.0.0", "summary": "On-brand, audited images and copy from your Abni folders.", "description": "Everything the Abni studio does, over HTTPS. Folders nest three deep (Level 1 → Level 2 → Level 3); each level inherits the brand style, rules and references of the folders above it.\n\nFolder names: `level1` / `level2` / `level3` are accepted in the path, query string and JSON bodies. The older `brand` / `subBrand` / `campaign` (and `brandSlug` / `subBrandSlug` / `campaignSlug`) keep working.\n\nImage work is asynchronous: create calls return `202` with an `id`; poll `GET /v1/images/{imageId}` until `status` is `completed` or `failed`, or receive a webhook.\n\nGet an API key from **Settings › API & automation** in the dashboard (workspace admins, paid workspaces). Full guide: https://abni.ai/api-docs.html", "contact": { "name": "Abni", "email": "team@abni.ai", "url": "https://abni.ai/api-docs.html" } }, "servers": [ { "url": "https://api.abni.ai", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Folders", "description": "Level 1, 2 and 3 folders." }, { "name": "Images", "description": "Generate, brandify, edit, resize and improve images." }, { "name": "Library", "description": "Images stored in a folder." }, { "name": "Style", "description": "Golden references and style extraction." }, { "name": "Text", "description": "On-brand copy and proofreading." }, { "name": "Designs", "description": "Banners laid out with the folder's fonts, logo and design colours." }, { "name": "Credits", "description": "Prices and spend." } ], "paths": { "/v1/folders": { "get": { "tags": [ "Folders" ], "operationId": "listFolders", "summary": "List Level 1 folders", "parameters": [ { "$ref": "#/components/parameters/withHero" }, { "$ref": "#/components/parameters/includeStats" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "level1Folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderSummary" } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "post": { "tags": [ "Folders" ], "operationId": "createFolder", "summary": "Create a folder", "description": "No parent creates a Level 1 folder; `level1` creates a Level 2 folder inside it; `level1` + `level2` creates a Level 3 folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "slug": { "type": "string" }, "level1": { "type": "string" }, "level2": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/Folder" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/folders/{level1}": { "parameters": [ { "$ref": "#/components/parameters/level1Path" } ], "patch": { "tags": [ "Folders" ], "operationId": "renameFolder", "summary": "Rename a folder", "description": "Add `level2` / `level3` to target a deeper folder. The slug never changes.", "parameters": [ { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/Folder" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } }, "delete": { "tags": [ "Folders" ], "operationId": "deleteFolder", "summary": "Delete a folder", "description": "Soft delete. A folder with live folders inside it returns `409 HAS_CHILDREN`.", "parameters": [ { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "$ref": "#/components/schemas/Folder" }, "deleted": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/folders/{level1}/tree": { "parameters": [ { "$ref": "#/components/parameters/level1Path" } ], "get": { "tags": [ "Folders" ], "operationId": "getFolderTree", "summary": "A Level 1 folder with its Level 2 and Level 3 folders", "parameters": [ { "$ref": "#/components/parameters/withHero" }, { "$ref": "#/components/parameters/includeStats" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "level1Folder": { "$ref": "#/components/schemas/FolderSummary" }, "level2Folders": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FolderSummary" }, { "type": "object", "properties": { "level3Folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderSummary" } } } } ] } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/images": { "post": { "tags": [ "Images" ], "operationId": "createImage", "summary": "Generate an image", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "prompt": { "type": "string", "maxLength": 4000 }, "aspectRatio": { "$ref": "#/components/schemas/AspectRatio" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "outputFormat": { "type": "string", "enum": [ "png", "jpg" ], "default": "png" }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" } }, "required": [ "level1", "prompt" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/Accepted" }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/images/{imageId}": { "parameters": [ { "$ref": "#/components/parameters/imageId" } ], "get": { "tags": [ "Images" ], "operationId": "getImage", "summary": "Get an image and its versions", "description": "Poll until `status` is `completed` or `failed`. Image links are signed and expire after an hour.", "parameters": [ { "$ref": "#/components/parameters/level1Query" }, { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Image" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/images/brandify": { "post": { "tags": [ "Images" ], "operationId": "brandifyImage", "summary": "Re-style an external image in a folder's brand style", "description": "JSON with `sourceUrl` (https, max 20 MB), or multipart with the file in a `source` field. The original is kept as version 1; the brandified image is version 2.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "instructions": { "type": "string" }, "aspectRatio": { "$ref": "#/components/schemas/AspectRatio" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "outputFormat": { "type": "string", "enum": [ "png", "jpg" ] }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" } }, "required": [ "level1", "sourceUrl" ] } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "instructions": { "type": "string" }, "aspectRatio": { "$ref": "#/components/schemas/AspectRatio" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" }, "source": { "type": "string", "contentMediaType": "image/*" } }, "required": [ "level1", "source" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/Accepted" }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" } } } }, "/v1/images/{imageId}/revise": { "parameters": [ { "$ref": "#/components/parameters/imageId" } ], "post": { "tags": [ "Images" ], "operationId": "reviseImage", "summary": "Edit an image (new version)", "parameters": [ { "$ref": "#/components/parameters/level1Query" }, { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instructions": { "type": "string", "maxLength": 4000 }, "fromVersion": { "type": "integer" }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" } }, "required": [ "instructions" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/VersionAccepted" }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/images/{imageId}/resize": { "parameters": [ { "$ref": "#/components/parameters/imageId" } ], "post": { "tags": [ "Images" ], "operationId": "resizeImage", "summary": "Resize or reframe an image (new version)", "parameters": [ { "$ref": "#/components/parameters/level1Query" }, { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aspectRatio": { "$ref": "#/components/schemas/AspectRatio" }, "resolution": { "$ref": "#/components/schemas/Resolution" }, "outputFormat": { "type": "string", "enum": [ "png", "jpg" ], "default": "png" }, "fromVersion": { "type": "integer" }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" } }, "required": [ "aspectRatio", "resolution" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/VersionAccepted" }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/images/{imageId}/improve": { "parameters": [ { "$ref": "#/components/parameters/imageId" } ], "post": { "tags": [ "Images" ], "operationId": "improveImage", "summary": "Check an image against the brand and fix it (new version)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "instructions": { "type": "string", "maxLength": 4000 }, "fromVersion": { "type": "integer" }, "clientReferenceId": { "$ref": "#/components/schemas/ClientReferenceId" } }, "required": [ "level1" ] } } } }, "responses": { "202": { "$ref": "#/components/responses/VersionAccepted" }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/library": { "get": { "tags": [ "Library" ], "operationId": "listLibrary", "summary": "Images in a folder, newest first", "parameters": [ { "name": "level1", "in": "query", "description": "The Level 1 folder (older name: `brandSlug`). Leave out to list the whole workspace.", "schema": { "type": "string" } }, { "name": "level2", "in": "query", "description": "Narrow to a Level 2 folder (older name: `subBrandSlug`).", "schema": { "type": "string" } }, { "name": "level3", "in": "query", "description": "Narrow to a Level 3 folder (older name: `campaignSlug`); needs `level2`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "latest", "oldest", "score", "hero" ], "default": "latest" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryItem" } }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } }, "post": { "tags": [ "Library" ], "operationId": "addToLibrary", "summary": "Add an image to a folder's library", "description": "`imageUrl` is a public https link (fetched for you) or the `s3Key` from a presigned upload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "imageUrl": { "type": "string" }, "filename": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "level1", "imageUrl" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "object", "properties": { "imageId": { "type": "string" }, "url": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" } } } }, "/v1/library/{imageId}/download": { "parameters": [ { "$ref": "#/components/parameters/imageId" } ], "get": { "tags": [ "Library" ], "operationId": "downloadLibraryImage", "summary": "A short-lived download link (original, JPEG or WebP)", "parameters": [ { "name": "level1", "in": "query", "required": true, "description": "The image's folder (older name: `brandSlug`).", "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "jpeg", "webp" ] } }, { "name": "maxSide", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 4096, "default": 1600 } }, { "name": "quality", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 82 } }, { "name": "filename", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/folders/{level1}/golden-refs/{domain}": { "parameters": [ { "$ref": "#/components/parameters/level1Path" }, { "$ref": "#/components/parameters/domain" } ], "get": { "tags": [ "Style" ], "operationId": "listGoldenRefs", "summary": "A folder's golden references", "parameters": [ { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "currentVersion": { "type": "integer" }, "refs": { "type": "array", "items": { "type": "object", "properties": { "refId": { "type": "string" }, "category": { "type": "string" }, "filename": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/folders/{level1}/golden-refs/{domain}/from-library": { "parameters": [ { "$ref": "#/components/parameters/level1Path" }, { "$ref": "#/components/parameters/domain" } ], "post": { "tags": [ "Style" ], "operationId": "addGoldenRefsFromLibrary", "summary": "Make library images golden references", "description": "Up to 5 references per folder. The images must already be in the library at the same level. `replace: true` starts a fresh set.", "parameters": [ { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "libraryImageIds": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string", "enum": [ "hero", "asset", "product", "general" ] }, "replace": { "type": "boolean" } }, "required": [ "libraryImageIds" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "array", "items": {} }, "totalCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/folders/{level1}/extract-jobs": { "parameters": [ { "$ref": "#/components/parameters/level1Path" } ], "post": { "tags": [ "Style" ], "operationId": "startExtraction", "summary": "Learn a folder's style from its golden references", "parameters": [ { "$ref": "#/components/parameters/level2Query" }, { "$ref": "#/components/parameters/level3Query" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "photo", "illustration", "document" ] }, "websiteUrl": { "type": "string" }, "autoApproveRules": { "type": "boolean" }, "keepColours": { "type": "boolean" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/folders/{level1}/extract-jobs/{jobId}": { "parameters": [ { "$ref": "#/components/parameters/level1Path" }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Style" ], "operationId": "getExtraction", "summary": "Extraction progress and result", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "progress": { "type": "object", "properties": { "step": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "number" } } }, "result": { "type": "object" }, "error": {}, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/text/generate": { "post": { "tags": [ "Text" ], "operationId": "generateText", "summary": "On-brand copy in a folder's voice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "mode": { "type": "string", "enum": [ "write", "rebrand", "amend", "resize" ] }, "brief": { "type": "string", "maxLength": 4000 }, "draft": { "type": "string", "maxLength": 20000 }, "instruction": { "type": "string" }, "target": { "type": "string" }, "format": { "type": "string" } }, "required": [ "level1", "mode" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "markdown": { "type": "string" }, "itemId": { "type": "string" }, "version": { "type": "integer" }, "credits": { "type": "object", "properties": { "deducted": { "type": "number" }, "balance": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/text/proofread": { "post": { "tags": [ "Text" ], "operationId": "proofreadText", "summary": "Proofread against a folder's house rules (free)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 50000 }, "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" } }, "required": [ "text", "level1" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "corrected": { "type": "string" }, "markdown": { "type": "string" }, "applied": { "type": "array", "items": {} }, "advisories": { "type": "array", "items": {} }, "rulesChecked": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/designs": { "post": { "tags": [ "Designs" ], "operationId": "createBanner", "summary": "Make a banner (async)", "description": "Words are drawn exactly as sent. Each version is checked for WCAG AA contrast, busy-photo placement, logo clear space and minimum size, then a design check. Charged `banner_create` per version (a master template such as `article-cover-panel`: `banner_cover`); failed versions are refunded. When no crop keeps the photo's subject clear of the words, the photo is extended on the text side, charged `banner_extend` only when that runs. Poll `GET /v1/designs/{jobId}`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "size": { "type": "string", "enum": [ "linkedin-cover", "linkedin-feed", "square", "portrait", "email-header" ] }, "template": { "type": "string", "enum": [ "overlay", "split", "panel", "all", "article-cover-panel" ], "default": "all", "description": "`all` = one version each of overlay, split and panel. `article-cover-panel` is a master template: one version, needs `slots.imageId`, sizes linkedin-cover or linkedin-feed." }, "slots": { "type": "object", "properties": { "headline": { "type": "string", "maxLength": 140 }, "subhead": { "type": "string", "maxLength": 200 }, "buttonText": { "type": "string", "maxLength": 40 }, "authorRole": { "type": "string", "maxLength": 60, "description": "Byline role (article-cover-panel)." }, "authorName": { "type": "string", "maxLength": 60, "description": "Byline name (article-cover-panel)." }, "imageId": { "type": "string", "description": "A library image in this folder or a folder above." }, "logo": { "type": "string", "description": "Logo name; default the folder's primary logo; \"none\" for no logo." } }, "required": [ "headline" ] } }, "required": [ "level1", "size", "slots" ] } } } }, "responses": { "202": { "description": "Accepted — poll GET /v1/designs/{jobId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "const": "queued" }, "templates": { "type": "array", "items": { "type": "string" } }, "credits": { "type": "object", "properties": { "deducted": { "type": "number" }, "balance": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } } }, "/v1/designs/{jobId}": { "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Designs" ], "operationId": "getBanner", "summary": "Banner job status, PNG URLs and layouts", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "progress": { "type": "string" }, "error": { "type": "string" }, "size": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string" }, "template": { "type": "string" }, "pngUrl": { "type": "string", "description": "Valid for 1 hour." }, "spec": { "type": "object", "description": "The DesignSpec." }, "scores": { "type": "object" }, "assessment": { "type": "string" }, "fixPasses": { "type": "integer" }, "contrastFailures": { "type": "array", "items": {} }, "warnings": { "type": "array", "items": { "type": "string" } }, "savedImageId": { "type": "string" } } } }, "dropped": { "type": "array", "items": { "type": "object", "properties": { "template": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" } } }, "post": { "tags": [ "Designs" ], "operationId": "saveBanner", "summary": "Save a banner version to the library", "description": "Charged as `upload`. Saving the same version again returns the same imageId with alreadySaved: true and no charge. With `intoImageId` (a saved design in the same folder as the job) the banner becomes the next version of that design: same imageId, the new headline becomes its title, and each version keeps its own recipe. 404 DESIGN_NOT_FOUND (not a saved design in that folder) comes before any charge; 409 DESIGN_BUSY when another save into the same design is running.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string" }, "intoImageId": { "type": "string", "description": "Library id of a saved design to add this as a new version of." } }, "required": [ "variantId" ] } } } }, "responses": { "200": { "description": "Already saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageId": { "type": "string" }, "version": { "type": "integer" }, "alreadySaved": { "type": "boolean" } } } } } }, "201": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "imageId": { "type": "string" }, "version": { "type": "integer", "description": "Only with intoImageId: the new version number." }, "credits": { "type": "object", "properties": { "deducted": { "type": "number" }, "balance": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" } } } }, "/v1/pricing": { "get": { "tags": [ "Credits" ], "operationId": "getPricing", "summary": "Your credit price per operation", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "prices": { "type": "object", "additionalProperties": { "type": "number" } }, "updatedAt": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } }, "/v1/credits/transactions": { "get": { "tags": [ "Credits" ], "operationId": "listTransactions", "summary": "Your credit ledger, newest first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "level1", "in": "query", "description": "Only this Level 1 folder's charges and refunds, plus totals.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "ISO date/time lower bound when `level1` is set.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "txnId": { "type": "string" }, "type": { "type": "string" }, "credits": { "type": "number" }, "balanceAfter": { "type": "number" }, "scope": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string" }, "metadata": { "type": "object" } } } }, "totals": { "type": "object", "properties": { "charged": { "type": "number" }, "refunded": { "type": "number" }, "net": { "type": "number" } } }, "truncated": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your workspace API key. Keep it server-side. Each key has a level — Read only (GETs), Create (read + making images, text, library adds, folders, extraction) or Full access (everything, incl. deletes and brand settings). A call above the key's level returns 403 INSUFFICIENT_SCOPE." } }, "parameters": { "imageId": { "name": "imageId", "in": "path", "required": true, "description": "The image id from a create call, or a library image id.", "schema": { "type": "string" } }, "level1Path": { "name": "level1", "in": "path", "required": true, "description": "The Level 1 folder slug.", "schema": { "type": "string" } }, "level1Query": { "name": "level1", "in": "query", "required": true, "description": "The image's Level 1 folder (older name: `brand`).", "schema": { "type": "string" } }, "level2Query": { "name": "level2", "in": "query", "description": "A Level 2 folder inside the Level 1 folder (older name: `subBrand`).", "schema": { "type": "string" } }, "level3Query": { "name": "level3", "in": "query", "description": "A Level 3 folder inside the Level 2 folder (older name: `campaign`).", "schema": { "type": "string" } }, "domain": { "name": "domain", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "photos", "designs" ] } }, "withHero": { "name": "withHero", "in": "query", "description": "Include each folder's hero image.", "schema": { "type": "boolean" } }, "includeStats": { "name": "include", "in": "query", "description": "`stats` adds counts.", "schema": { "type": "string", "enum": [ "stats" ] } } }, "responses": { "Accepted": { "description": "Accepted — poll GET /v1/images/{imageId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "status": { "type": "string", "const": "processing" } } } } } }, "VersionAccepted": { "description": "Accepted — a new version is being made", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "version": { "type": "integer" }, "basedOn": { "type": "integer" }, "status": { "type": "string", "const": "processing" } } } } } }, "E400": { "description": "Bad request (VALIDATION_ERROR, MISSING_BODY, FOLDER_ALIAS_CONFLICT, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No API key sent (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Not enough credits (INSUFFICIENT_CREDITS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Key not recognised or revoked (INVALID_API_KEY), key level too low (INSUFFICIENT_SCOPE), workspace paused (CLIENT_PAUSED) or not allowed (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found (NOT_FOUND, FOLDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (ALREADY_PROCESSING, HAS_CHILDREN, EXTRACTION_IN_PROGRESS, …)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "File too large (PAYLOAD_TOO_LARGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E415": { "description": "Not an image (UNSUPPORTED_MEDIA_TYPE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "AspectRatio": { "type": "string", "enum": [ "1:1", "4:5", "9:16", "16:9", "2:3", "5:4" ], "default": "1:1" }, "Resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "2K" }, "ClientReferenceId": { "type": "string", "maxLength": 200, "description": "Echoed back on GET and in webhook payloads." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Branch on this, never on the message. Examples: VALIDATION_ERROR, INSUFFICIENT_CREDITS, FOLDER_NOT_FOUND." }, "message": { "type": "string" }, "details": { "type": "object", "description": "For FOLDER_NOT_FOUND: { level, level1, level2?, level3? } — `level` (1, 2 or 3) is the missing folder's level." }, "requestId": { "type": "string", "description": "Include in support requests." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Folder": { "type": "object", "properties": { "level": { "type": "integer", "enum": [ 1, 2, 3 ] }, "slug": { "type": "string" }, "name": { "type": "string" }, "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "FolderSummary": { "type": "object", "properties": { "level": { "type": "integer", "enum": [ 1, 2, 3 ] }, "slug": { "type": "string" }, "name": { "type": "string" }, "level1": { "type": "string" }, "level2": { "type": "string" }, "hero": { "type": [ "object", "null" ] } } }, "ImageVersion": { "type": "object", "properties": { "version": { "type": "integer" }, "url": { "type": "string" }, "createdAt": { "type": "string" }, "prompt": { "type": "string" }, "aspectRatio": { "type": "string" }, "resolution": { "type": "string" }, "outputFormat": { "type": "string" }, "score": { "type": "number" } } }, "Image": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ] }, "imageUrl": { "type": [ "string", "null" ] }, "currentVersion": { "type": "integer" }, "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" }, "clientReferenceId": { "type": "string" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ImageVersion" } }, "error": {} } }, "LibraryItem": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "thumbnailUrl": { "type": "string" }, "title": { "type": "string" }, "score": { "type": "number" }, "currentVersion": { "type": "integer" }, "isGoldenRef": { "type": "boolean" }, "level1": { "type": "string" }, "level2": { "type": "string" }, "level3": { "type": "string" } } } } } }