{ "info": { "title": "Flora.ai API", "version": "1.6.0", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://app.flora.ai/api/v1" } ], "tags": [ { "name": "Actions", "description": "Prebuilt action catalog endpoints." }, { "name": "Workspaces", "description": "Workspace discovery endpoints." }, { "name": "Projects", "description": "Project management endpoints." }, { "name": "Models", "description": "Model catalog endpoints." }, { "name": "Techniques", "description": "Technique catalog endpoints." }, { "name": "Technique Runs", "description": "Nested technique run endpoints." }, { "name": "Assets", "description": "Asset upload and retrieval endpoints." }, { "name": "Runs", "description": "Top-level run creation endpoints." }, { "name": "Canvas", "description": "Project canvas endpoints." }, { "name": "Feedback", "description": "Product feedback endpoints." }, { "name": "Generations", "description": "Generation endpoints." } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Flora API key" } } }, "openapi": "3.1.1", "paths": { "/actions": { "get": { "operationId": "listActions", "summary": "List actions", "description": "Returns released prebuilt Flora actions that can be executed by the public API. Action identifiers are raw slugs such as rotate-image, not action-prefixed IDs.", "tags": [ "Actions" ], "parameters": [], "responses": { "200": { "description": "Actions returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] }, "name": { "type": "string", "description": "Action name", "examples": [ "Rotate Image" ] }, "description": { "type": "string", "description": "Action description", "examples": [ "Rotate an image by a fixed angle." ] }, "language": { "enum": [ "javascript", "python" ], "type": "string", "description": "Action runtime language" }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost per execution in USD" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Action input or output name", "examples": [ "image" ] }, "type": { "enum": [ "image", "video", "text", "audio" ], "type": "string", "description": "Action input or output media type" }, "dynamic": { "type": "boolean", "description": "Whether the slot accepts multiple values" } }, "required": [ "name", "type" ] }, "description": "Action input slots" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Action input or output name", "examples": [ "image" ] }, "type": { "enum": [ "image", "video", "text", "audio" ], "type": "string", "description": "Action input or output media type" }, "dynamic": { "type": "boolean", "description": "Whether the slot accepts multiple values" } }, "required": [ "name", "type" ] }, "description": "Action output slots" }, "params": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Action parameter key", "examples": [ "angle" ] }, "type": { "type": "string", "description": "Action parameter control type", "examples": [ "select" ] }, "label": { "type": "string", "description": "Action parameter label", "examples": [ "Angle" ] }, "info_tooltip": { "type": "string", "description": "Action parameter description", "examples": [ "Rotation angle in degrees." ] }, "default_value": { "description": "Default parameter value" }, "available_values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Allowed parameter values" }, "min_number_value": { "type": "number" }, "max_number_value": { "type": "number" }, "number_step": { "type": "number" } }, "required": [ "key", "type" ] }, "description": "Action parameters" } }, "required": [ "action_id", "name", "description", "language", "charged_cost", "inputs", "outputs", "params" ] } } }, "required": [ "actions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/actions/{actionId}": { "get": { "operationId": "getAction", "summary": "Get an action", "description": "Returns metadata for one released prebuilt Flora action. Action identifiers are raw slugs such as rotate-image, not action-prefixed IDs.", "tags": [ "Actions" ], "parameters": [ { "name": "actionId", "in": "path", "required": true, "schema": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] }, "description": "Action identifier" } ], "responses": { "200": { "description": "Action returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] }, "name": { "type": "string", "description": "Action name", "examples": [ "Rotate Image" ] }, "description": { "type": "string", "description": "Action description", "examples": [ "Rotate an image by a fixed angle." ] }, "language": { "enum": [ "javascript", "python" ], "type": "string", "description": "Action runtime language" }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost per execution in USD" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Action input or output name", "examples": [ "image" ] }, "type": { "enum": [ "image", "video", "text", "audio" ], "type": "string", "description": "Action input or output media type" }, "dynamic": { "type": "boolean", "description": "Whether the slot accepts multiple values" } }, "required": [ "name", "type" ] }, "description": "Action input slots" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Action input or output name", "examples": [ "image" ] }, "type": { "enum": [ "image", "video", "text", "audio" ], "type": "string", "description": "Action input or output media type" }, "dynamic": { "type": "boolean", "description": "Whether the slot accepts multiple values" } }, "required": [ "name", "type" ] }, "description": "Action output slots" }, "params": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Action parameter key", "examples": [ "angle" ] }, "type": { "type": "string", "description": "Action parameter control type", "examples": [ "select" ] }, "label": { "type": "string", "description": "Action parameter label", "examples": [ "Angle" ] }, "info_tooltip": { "type": "string", "description": "Action parameter description", "examples": [ "Rotation angle in degrees." ] }, "default_value": { "description": "Default parameter value" }, "available_values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Allowed parameter values" }, "min_number_value": { "type": "number" }, "max_number_value": { "type": "number" }, "number_step": { "type": "number" } }, "required": [ "key", "type" ] }, "description": "Action parameters" } }, "required": [ "action_id", "name", "description", "language", "charged_cost", "inputs", "outputs", "params" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List accessible workspaces", "description": "Returns the workspaces available to the authenticated public API key, including each workspace's public ID, name, creation timestamp, and caller role.", "tags": [ "Workspaces" ], "parameters": [], "responses": { "200": { "description": "Accessible workspaces returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "name": { "type": "string", "description": "Workspace name", "examples": [ "Brand Studio" ] }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "role": { "type": "string", "description": "Workspace role" } }, "required": [ "workspace_id", "name", "created_at", "role" ] } } }, "required": [ "workspaces" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List workspace projects", "description": "Returns projects in the requested workspace that are accessible to the authenticated public API key, ordered by recent activity.", "tags": [ "Projects" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of results to return" }, "allowEmptyValue": true, "allowReserved": true, "description": "Maximum number of results to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque cursor for fetching the next page" }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query", "examples": [ "logo" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Search query" }, { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Workspace identifier" } ], "responses": { "200": { "description": "Projects returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "name": { "type": "string", "description": "Project name", "examples": [ "Spring Campaign" ] }, "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "origin": { "anyOf": [ { "type": "string", "description": "Project origin", "examples": [ "api" ] }, { "type": "null" } ], "description": "Project origin" }, "last_modified": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "type": "number" } }, "required": [ "project_id", "name", "workspace_id", "origin", "last_modified", "created_at" ] } }, "meta": { "type": "object", "properties": { "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, { "type": "null" } ], "description": "Opaque cursor for fetching the next page" }, "total_estimate": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Estimated total matching items" }, { "type": "null" } ], "description": "Estimated total matching items" } }, "required": [ "next_cursor" ] } }, "required": [ "projects", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates a new Flora project in the requested workspace. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace_id", "name" ], "additionalProperties": false, "properties": { "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "name": { "type": "string", "minLength": 1, "description": "Project name", "examples": [ "Spring Campaign" ] } } } } } }, "responses": { "201": { "description": "Project created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "name": { "type": "string", "description": "Project name", "examples": [ "Spring Campaign" ] }, "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "origin": { "anyOf": [ { "type": "string", "description": "Project origin", "examples": [ "api" ] }, { "type": "null" } ], "description": "Project origin" }, "last_modified": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "type": "number" } }, "required": [ "project_id", "name", "workspace_id", "origin", "last_modified", "created_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get a project", "description": "Returns metadata for a single project when it is accessible to the authenticated public API key. Missing and inaccessible projects both return 404.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" } ], "responses": { "200": { "description": "Project returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "name": { "type": "string", "description": "Project name", "examples": [ "Spring Campaign" ] }, "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "origin": { "anyOf": [ { "type": "string", "description": "Project origin", "examples": [ "api" ] }, { "type": "null" } ], "description": "Project origin" }, "last_modified": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "type": "number" } }, "required": [ "project_id", "name", "workspace_id", "origin", "last_modified", "created_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}/canvas": { "get": { "operationId": "getProjectCanvas", "summary": "Get project canvas", "description": "Returns the current project canvas topology as a Mermaid flowchart using the same serializer as the Fauna agent.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" } ], "responses": { "200": { "description": "Project canvas returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "canvas_url": { "type": "string", "format": "uri", "description": "Project canvas URL" }, "diagram": { "type": "string", "minLength": 1, "description": "Mermaid flowchart diagram", "examples": [ "graph LR\n n1[\"Prompt (text)\"]\n n2[\"Result (image)\"]\n n1 -->|text| n2" ] }, "summary": { "type": "object", "properties": { "node_count": { "type": "integer", "minimum": 0 }, "edge_count": { "type": "integer", "minimum": 0 }, "workflow_count": { "type": "integer", "minimum": 0 }, "isolated_node_count": { "type": "integer", "minimum": 0 }, "group_count": { "type": "integer", "minimum": 0 } }, "required": [ "node_count", "edge_count", "workflow_count", "isolated_node_count", "group_count" ] } }, "required": [ "project_id", "canvas_url", "diagram", "summary" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } }, "patch": { "operationId": "patchProjectCanvas", "summary": "Patch project canvas", "description": "Applies a Mermaid flowchart patch to the project canvas using the same create_workflow path as the Fauna agent. The diagram may add nodes, connect nodes, and reference existing canvas nodes by their Mermaid short IDs.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "diagram": { "type": "string", "minLength": 1, "description": "Mermaid flowchart diagram to apply", "examples": [ "graph LR\n source[\"Product photo (Image)\"]\n output[\"Editorial campaign image (Image)\"]\n source --> output" ] }, "node_params": { "type": "object", "additionalProperties": { "type": "object", "properties": { "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "aspect_ratio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "model_parameters": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } } }, "description": "Optional per-node parameters keyed by Mermaid node ID." } }, "required": [ "diagram" ] } } } }, "responses": { "200": { "description": "Project canvas patched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "canvas_url": { "type": "string", "format": "uri", "description": "Project canvas URL" }, "diagram": { "type": "string", "minLength": 1, "description": "Applied Mermaid flowchart diagram", "examples": [ "graph LR\n n1[\"Prompt (text)\"]\n n2[\"Result (image)\"]\n n1 --> n2" ] }, "created_node_count": { "type": "integer", "minimum": 0 }, "created_edge_count": { "type": "integer", "minimum": 0 }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "project_id", "canvas_url", "diagram", "created_node_count", "created_edge_count" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}/actions": { "post": { "operationId": "createCanvasAction", "summary": "Create a canvas action", "description": "Creates a prebuilt action node on a project canvas using a raw action slug.", "tags": [ "Canvas" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] }, "params": { "type": "object", "additionalProperties": {}, "description": "Action parameters" } }, "required": [ "action_id" ] } } } }, "responses": { "201": { "description": "Canvas action created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "node_id": { "type": "string", "minLength": 1, "description": "Canvas action node identifier", "examples": [ "node_abc123" ] }, "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] }, "canvas_url": { "type": "string", "format": "uri", "description": "Project canvas URL" } }, "required": [ "project_id", "node_id", "action_id", "canvas_url" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}/actions/{nodeId}/run": { "post": { "operationId": "runCanvasAction", "summary": "Run a canvas action", "description": "Runs an existing canvas action node through the action execution workflow.", "tags": [ "Canvas" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" }, { "name": "nodeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\S+$", "description": "Canvas action node identifier" }, "description": "Canvas action node identifier" } ], "responses": { "201": { "description": "Canvas action run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "type": { "enum": [ "generation", "technique", "action" ], "type": "string", "description": "Run type" }, "model": { "anyOf": [ { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] } }, "required": [ "model_id" ] }, { "type": "null" } ] }, "technique": { "anyOf": [ { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name" } }, "required": [ "technique_id", "name" ] }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] } }, "required": [ "action_id" ] }, { "type": "null" } ] }, "estimated_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "poll_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "run_id", "type", "estimated_seconds", "charged_cost" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/models": { "get": { "operationId": "listModels", "summary": "List available models", "description": "Returns the public model catalog visible to API clients. Use the optional type filter to narrow results to image, video, audio, or text models.", "tags": [ "Models" ], "parameters": [ { "name": "type", "in": "query", "schema": { "enum": [ "image", "video", "audio", "text" ], "type": "string", "description": "Model type" }, "allowEmptyValue": true, "allowReserved": true, "description": "Model type" } ], "responses": { "200": { "description": "Available models returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] }, "name": { "type": "string", "description": "Model name" }, "type": { "enum": [ "image", "video", "audio", "text" ], "type": "string", "description": "Model type" }, "provider": { "type": "string", "description": "Model provider", "examples": [ "Black Forest Labs" ] }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Model capability" }, "description": "Model capabilities" }, "estimated_credits": { "type": "integer", "minimum": 0, "description": "Estimated credits" }, "estimated_seconds": { "type": "integer", "minimum": 0, "description": "Estimated seconds" }, "params": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Parameter name to pass in generation params" }, "type": { "enum": [ "string", "string[]", "bool", "int", "int?", "seed", "float", "dict" ], "type": "string", "description": "Parameter value type" }, "required": { "type": "boolean", "description": "Whether the model requires this parameter" }, "default": { "description": "Default parameter value" }, "min": { "type": "number", "description": "Minimum numeric value" }, "max": { "type": "number", "description": "Maximum numeric value" }, "label": { "type": "string", "description": "Human-readable parameter label" }, "description": { "type": "string", "description": "Parameter help text" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Displayed option label" }, "value": { "type": "string", "description": "Option value to pass in generation params" }, "description": { "type": "string", "description": "Option description" } }, "required": [ "label", "value" ] }, "description": "Allowed values for enum-like parameters" }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } }, "required": [ "min", "max", "default" ] }, "description": "Nested numeric properties for object parameters" } }, "required": [ "name", "type", "required" ] }, "description": "Supported generation parameters for this model" }, "beta": { "type": "boolean", "description": "Whether this model is in beta" } }, "required": [ "model_id", "name", "type", "provider", "capabilities", "estimated_credits", "estimated_seconds", "params" ] } } }, "required": [ "models" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/techniques": { "get": { "operationId": "listTechniques", "summary": "List techniques", "description": "Returns reusable Flora techniques visible to the authenticated public API key. Use workspace_id, query, cursor, and limit to filter the catalog.", "tags": [ "Techniques" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of results to return" }, "allowEmptyValue": true, "allowReserved": true, "description": "Maximum number of results to return" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque cursor for fetching the next page" }, { "name": "query", "in": "query", "schema": { "type": "string", "description": "Search query", "examples": [ "logo" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Search query" }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Workspace identifier" } ], "responses": { "200": { "description": "Techniques returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "techniques": { "type": "array", "items": { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name", "examples": [ "Editorial Image Grid" ] }, "description": { "type": "string", "description": "Technique description", "examples": [ "Generate a cohesive editorial image grid." ] }, "run_cost": { "type": "number", "minimum": 0, "description": "Cost per run in USD" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Technique input or output identifier", "examples": [ "prompt" ] }, "name": { "type": "string", "description": "Technique input or output display name", "examples": [ "Prompt" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Technique input or output media type" }, "description": { "type": "string", "description": "Technique input or output description", "examples": [ "Describe the desired image." ] }, "specified_aspect_ratio": { "type": "string", "description": "Required aspect ratio", "examples": [ "1:1" ] }, "specified_duration": { "type": "number", "description": "Required duration in seconds" } }, "required": [ "id", "name", "type" ] } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Technique input or output identifier", "examples": [ "prompt" ] }, "name": { "type": "string", "description": "Technique input or output display name", "examples": [ "Prompt" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Technique input or output media type" }, "description": { "type": "string", "description": "Technique input or output description", "examples": [ "Describe the desired image." ] }, "specified_aspect_ratio": { "type": "string", "description": "Required aspect ratio", "examples": [ "1:1" ] }, "specified_duration": { "type": "number", "description": "Required duration in seconds" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "technique_id", "name", "run_cost", "inputs", "outputs" ] } }, "meta": { "type": "object", "properties": { "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, { "type": "null" } ], "description": "Opaque cursor for fetching the next page" }, "total_estimate": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Estimated total matching items" }, { "type": "null" } ], "description": "Estimated total matching items" } }, "required": [ "next_cursor" ] } }, "required": [ "techniques", "meta" ] }, "examples": { "availableTechniques": { "summary": "Available techniques", "value": { "techniques": [ { "technique_id": "tech_art-directors-critique", "name": "Art Director's Critique", "description": "Analyze, critique, and redesign any creative asset.", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_auto-translate", "name": "Auto Translate", "description": "Translate text in images instantly", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_book-drop", "name": "Book Drop", "description": "Mocks up front and back book covers", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_cctv-cam", "name": "CCTV Cam", "description": "Any face, CCTV style", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_character-lock", "name": "Character Lock", "description": "One character, 6 different angles", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_cinematic-movie-generator", "name": "Cinematic Movie Stills", "description": "Generate film-quality scene stills", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_color-mapping", "name": "Segment Mapper", "description": "Color-codes every element in your image", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_color-transfer", "name": "Color Transfer", "description": "Apply color grading from any reference", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_earth-zoom-out", "name": "Earth Zoom Out", "description": "Zoom out to space from any scene", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_facade-swap", "name": "Facade Swap", "description": "Reskin buildings with new materials", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_fit-checks", "name": "Fit Check", "description": "Extract outfits & swap onto new looks", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_glam-shots", "name": "Glam Shots", "description": "Create polished makeup ads instantly", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_icon-pack", "name": "Icon Pack", "description": "Generate matched icon sets from a prompt", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_live-like-an-amsterdammer", "name": "Live like an Amsterdammer", "description": "Places you into everyday Amsterdam scenes", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_location-scouter", "name": "Location Scout", "description": "Scouts five views from a single location", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_logo-stylist", "name": "Logo Stylist", "description": "Stylize any logo with a new visual twist", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_memoji-me", "name": "Memoji Me", "description": "Turn any face into a custom memoji", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_moodboard-maker", "name": "Mood Board Maker", "description": "Eclectic mood board from a photo", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_mugshot", "name": "Mugshot", "description": "Turn any portrait into a mugshot", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_palette-pull", "name": "Palette Pull", "description": "Extract color palettes from any image", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_product-animator", "name": "Product Animator", "description": "Animate your product", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_product-lookbook-grid", "name": "Product Lookbook Grid", "description": "Turn products into styled grid layouts", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_product-motion", "name": "Product Motion", "description": "Animate product shots in one click", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_quick-reframe", "name": "Layout Resizer", "description": "Resize layouts for any aspect ratio", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_relight-technique", "name": "Relighting", "description": "Relights your photo", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_room-render", "name": "Room Render", "description": "Turn floor plans into realistic rooms", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_seamless-transition", "name": "Seamless Transition", "description": "Animate between any two frames", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_sigil", "name": "Sigil", "description": "Turns any image into an animated glyph", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_sketch-to-garment", "name": "Garment Sketch", "description": "One sketch, one final garment.", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_studio-blur", "name": "Studio Blur", "description": "Add pro depth-of-field blur to photos", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_studio-shot", "name": "Studio Shot", "description": "Turns any product into a studio-lit shoot", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_tarot-pull", "name": "Tarot Pull", "description": "Custom illustrated tarot card readings", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_texture-matchers", "name": "Texture Match", "description": "Replicate textures & colors across assets", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_turn-any-product-into-4-ad-visuals", "name": "Turn any product into 4 ad visuals", "description": "Make a full ad campaign from 1 product", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_ugc-creation", "name": "UGC Creator", "description": "Casual, phone-shot clips of your product", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_video-scene-builder", "name": "Video Scene Builder", "description": "Compose video scenes from still assets", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_wireframe", "name": "Photo Wireframe", "description": "Turn any photo into a clean wireframe", "run_cost": 0, "inputs": [], "outputs": [] }, { "technique_id": "tech_wonder-fy", "name": "Wonder(fy)", "description": "Apply Wonder's cinematic style to images", "run_cost": 0, "inputs": [], "outputs": [] } ], "meta": { "next_cursor": null } } } } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/techniques/{techniqueId}": { "get": { "operationId": "getTechnique", "summary": "Get a technique", "description": "Returns the public definition for one technique, including its input and output schema used to start runs.", "tags": [ "Techniques" ], "parameters": [ { "name": "techniqueId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Technique identifier or slug", "examples": [ "art-directors-critique", "auto-translate", "book-drop", "cctv-cam", "character-lock", "cinematic-movie-generator", "color-mapping", "color-transfer" ], "pattern": "^\\S+$" }, "description": "Technique identifier or slug" } ], "responses": { "200": { "description": "Technique returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name", "examples": [ "Editorial Image Grid" ] }, "description": { "type": "string", "description": "Technique description", "examples": [ "Generate a cohesive editorial image grid." ] }, "run_cost": { "type": "number", "minimum": 0, "description": "Cost per run in USD" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Technique input or output identifier", "examples": [ "prompt" ] }, "name": { "type": "string", "description": "Technique input or output display name", "examples": [ "Prompt" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Technique input or output media type" }, "description": { "type": "string", "description": "Technique input or output description", "examples": [ "Describe the desired image." ] }, "specified_aspect_ratio": { "type": "string", "description": "Required aspect ratio", "examples": [ "1:1" ] }, "specified_duration": { "type": "number", "description": "Required duration in seconds" } }, "required": [ "id", "name", "type" ] } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Technique input or output identifier", "examples": [ "prompt" ] }, "name": { "type": "string", "description": "Technique input or output display name", "examples": [ "Prompt" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Technique input or output media type" }, "description": { "type": "string", "description": "Technique input or output description", "examples": [ "Describe the desired image." ] }, "specified_aspect_ratio": { "type": "string", "description": "Required aspect ratio", "examples": [ "1:1" ] }, "specified_duration": { "type": "number", "description": "Required duration in seconds" } }, "required": [ "id", "name", "type" ] } } }, "required": [ "technique_id", "name", "run_cost", "inputs", "outputs" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/techniques/{techniqueId}/runs": { "post": { "operationId": "startTechniqueRun", "summary": "Start a technique run", "description": "Starts a run for a specific technique using the backward-compatible nested route. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Technique Runs" ], "parameters": [ { "name": "techniqueId", "in": "path", "required": true, "schema": { "type": "string", "description": "Technique identifier or slug", "examples": [ "art-directors-critique", "auto-translate", "book-drop", "cctv-cam", "character-lock", "cinematic-movie-generator", "color-mapping", "color-transfer" ], "pattern": "^\\S+$" }, "description": "Technique identifier or slug" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "array", "description": "Technique inputs", "minItems": 1, "items": { "type": "object", "required": [ "id", "type", "value" ], "properties": { "id": { "type": "string", "description": "Technique input identifier" }, "type": { "type": "string", "enum": [ "text", "imageUrl", "videoUrl" ], "description": "Technique input type" }, "value": { "type": "string", "description": "Technique input value" } } } }, "mode": { "type": "string", "enum": [ "async", "stream" ], "description": "Technique run execution mode" }, "callback_url": { "type": "string", "format": "uri", "description": "HTTPS callback URL for asynchronous run completion notifications" }, "idempotency_key": { "type": "string", "description": "Idempotency key for safely retrying requests" } }, "required": [ "inputs", "mode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Technique run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "status": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string" }, "progress": { "type": "number" }, "created_at": { "type": "number" }, "started_at": { "type": "number" }, "completed_at": { "type": "number" }, "error_code": { "type": "string", "description": "Machine-readable run error code", "examples": [ "provider_error" ] }, "error_message": { "type": "string", "description": "Human-readable run error message", "examples": [ "The provider failed to complete the generation." ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "output_id": { "type": "string", "description": "Run output identifier", "examples": [ "output_1" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Run output media type" }, "url": { "type": "string", "format": "uri", "description": "Run output URL", "examples": [ "https://media.flora.ai/output.png" ] } }, "required": [ "output_id", "type", "url" ] } }, "poll_url": { "type": "string", "format": "uri" } }, "required": [ "run_id", "status", "progress", "created_at" ] } } } }, "201": { "description": "Technique run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "status": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string" }, "progress": { "type": "number" }, "created_at": { "type": "number" }, "started_at": { "type": "number" }, "completed_at": { "type": "number" }, "error_code": { "type": "string", "description": "Machine-readable run error code", "examples": [ "provider_error" ] }, "error_message": { "type": "string", "description": "Human-readable run error message", "examples": [ "The provider failed to complete the generation." ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "output_id": { "type": "string", "description": "Run output identifier", "examples": [ "output_1" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Run output media type" }, "url": { "type": "string", "format": "uri", "description": "Run output URL", "examples": [ "https://media.flora.ai/output.png" ] } }, "required": [ "output_id", "type", "url" ] } }, "poll_url": { "type": "string", "format": "uri" } }, "required": [ "run_id", "status", "progress", "created_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/techniques/{techniqueId}/runs/{runId}": { "get": { "operationId": "getTechniqueRun", "summary": "Get a technique run", "description": "Returns status, progress, outputs, and error details for a technique run when it is accessible to the authenticated public API key.", "tags": [ "Technique Runs" ], "parameters": [ { "name": "techniqueId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Technique identifier or slug", "examples": [ "art-directors-critique", "auto-translate", "book-drop", "cctv-cam", "character-lock", "cinematic-movie-generator", "color-mapping", "color-transfer" ], "pattern": "^\\S+$" }, "description": "Technique identifier or slug" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "description": "Run identifier" } ], "responses": { "200": { "description": "Technique run returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "status": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string" }, "progress": { "type": "number" }, "created_at": { "type": "number" }, "started_at": { "type": "number" }, "completed_at": { "type": "number" }, "error_code": { "type": "string", "description": "Machine-readable run error code", "examples": [ "provider_error" ] }, "error_message": { "type": "string", "description": "Human-readable run error message", "examples": [ "The provider failed to complete the generation." ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "output_id": { "type": "string", "description": "Run output identifier", "examples": [ "output_1" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Run output media type" }, "url": { "type": "string", "format": "uri", "description": "Run output URL", "examples": [ "https://media.flora.ai/output.png" ] } }, "required": [ "output_id", "type", "url" ] } }, "poll_url": { "type": "string", "format": "uri" } }, "required": [ "run_id", "status", "progress", "created_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/assets": { "get": { "operationId": "listAssets", "summary": "List assets", "description": "Returns assets visible to the authenticated public API key. Filter by workspace, project canvas, search query, cursor, and limit without exposing raw file bytes or internal graph data.", "tags": [ "Assets" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of results to return" }, "allowEmptyValue": true, "allowReserved": true, "description": "Maximum number of results to return" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque cursor for fetching the next page" }, { "name": "query", "in": "query", "schema": { "type": "string", "description": "Search query", "examples": [ "logo" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Search query" }, { "name": "workspace_id", "in": "query", "schema": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Workspace identifier" }, { "name": "project_id", "in": "query", "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Project identifier" } ], "responses": { "200": { "description": "Assets returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "anyOf": [ { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, { "type": "null" } ], "description": "Asset identifier" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset description" }, "workspace_id": { "anyOf": [ { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, { "type": "null" } ], "description": "Workspace identifier" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Asset URL" }, "content_type": { "type": "string", "description": "Asset content type" }, "upload_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Content type provided at upload time" }, "uploaded_via": { "type": "string", "description": "Asset source" }, "status": { "enum": [ "pending_upload", "ready", "failed" ], "type": "string" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "node_id": { "anyOf": [ { "type": "string", "description": "Associated node identifier", "examples": [ "node_abc123" ] }, { "type": "null" } ], "description": "Associated node identifier" }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "asset_id", "name", "description", "workspace_id", "url", "content_type", "upload_content_type", "uploaded_via", "status", "width", "height", "size_bytes", "created_at" ] } }, "meta": { "type": "object", "properties": { "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, { "type": "null" } ], "description": "Opaque cursor for fetching the next page" }, "total_estimate": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Estimated total matching items" }, { "type": "null" } ], "description": "Estimated total matching items" } }, "required": [ "next_cursor" ] } }, "required": [ "assets", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } }, "post": { "operationId": "uploadAsset", "summary": "Create an asset upload", "description": "Creates an asset from an allowlisted source URL or reserves a signed upload URL. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Assets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "workspace_id" ], "additionalProperties": false, "properties": { "source": { "type": "string", "description": "Asset source URL or signed-url upload mode", "examples": [ "signed-url", "https://example.com/source.png" ] }, "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "folder": { "type": "string", "description": "Destination folder", "examples": [ "campaign-assets" ] }, "content_type": { "type": "string", "description": "Asset content type", "examples": [ "image/png" ] }, "file_name": { "type": "string", "description": "Asset file name", "examples": [ "hero.png" ] } } } } } }, "responses": { "201": { "description": "Asset upload created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "uploaded_via": { "enum": [ "url", "signed_url" ], "type": "string", "description": "Asset source" }, "url": { "type": "string", "format": "uri", "description": "Asset URL" }, "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "visibility": { "const": "workspace" }, "status": { "enum": [ "pending_upload", "ready", "failed" ], "type": "string" }, "upload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Upload URL" }, "method": { "const": "POST" }, "content_type": { "const": "multipart/form-data" }, "file_field": { "const": "file" }, "form_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upload form fields" } }, "required": [ "url", "method", "content_type", "file_field", "form_fields" ] }, "upload_url": { "type": "string", "description": "Upload URL (serialized)", "examples": [ "https://upload.imagekit.io/api/v1/files/upload" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time for the upload URL" } }, "required": [ "asset_id", "uploaded_via", "url", "workspace_id", "visibility", "status" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/assets/{assetId}": { "get": { "operationId": "getAsset", "summary": "Get an asset", "description": "Returns metadata for one asset when it is accessible to the authenticated public API key. Missing and inaccessible assets both return 404.", "tags": [ "Assets" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "description": "Asset identifier" } ], "responses": { "200": { "description": "Asset returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Asset description" }, "workspace_id": { "anyOf": [ { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, { "type": "null" } ], "description": "Workspace identifier" }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Asset URL" }, "content_type": { "type": "string", "description": "Asset content type" }, "upload_content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Content type provided at upload time" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "uploaded_via": { "type": "string", "description": "Asset source" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Asset creation time (ISO 8601 datetime)" }, "status": { "enum": [ "pending_upload", "ready", "failed" ], "type": "string" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure message when the asset is in failed status" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "asset_id", "name", "description", "workspace_id", "url", "content_type", "upload_content_type", "size_bytes", "uploaded_via", "created_at", "status", "failure_message", "width", "height" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/assets/{assetId}/complete": { "post": { "operationId": "completeAssetUpload", "summary": "Complete a signed asset upload", "description": "Marks a signed asset upload as complete after the file has been uploaded. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Assets" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "description": "Asset identifier" } ], "responses": { "200": { "description": "Asset upload completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Asset URL" }, "workspace_id": { "anyOf": [ { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, { "type": "null" } ], "description": "Workspace identifier" }, "visibility": { "const": "workspace" }, "status": { "enum": [ "pending_upload", "ready", "failed" ], "type": "string" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure message when the asset is in failed status" }, "upload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Upload URL" }, "method": { "const": "POST" }, "content_type": { "const": "multipart/form-data" }, "file_field": { "const": "file" }, "form_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upload form fields" } }, "required": [ "url", "method", "content_type", "file_field", "form_fields" ] }, "upload_url": { "type": "string", "description": "Upload URL (serialized)", "examples": [ "https://upload.imagekit.io/api/v1/files/upload" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time for the upload URL" } }, "required": [ "asset_id", "url", "workspace_id", "visibility", "status" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/assets/{assetId}/retry": { "post": { "operationId": "retryAssetUpload", "summary": "Retry a signed asset upload", "description": "Creates a fresh signed upload reservation for a failed or expired asset upload. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Assets" ], "parameters": [ { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "description": "Asset identifier" } ], "responses": { "200": { "description": "Asset upload retry created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Asset URL" }, "workspace_id": { "anyOf": [ { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, { "type": "null" } ], "description": "Workspace identifier" }, "visibility": { "const": "workspace" }, "status": { "enum": [ "pending_upload", "ready", "failed" ], "type": "string" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure message when the asset is in failed status" }, "upload": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Upload URL" }, "method": { "const": "POST" }, "content_type": { "const": "multipart/form-data" }, "file_field": { "const": "file" }, "form_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Upload form fields" } }, "required": [ "url", "method", "content_type", "file_field", "form_fields" ] }, "upload_url": { "type": "string", "description": "Upload URL (serialized)", "examples": [ "https://upload.imagekit.io/api/v1/files/upload" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration time for the upload URL" } }, "required": [ "asset_id", "url", "workspace_id", "visibility", "status" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/runs/{runId}": { "get": { "operationId": "getRun", "summary": "Get a run", "description": "Returns status and completed output URLs for a public API run, including action runs started through POST /runs/action.", "tags": [ "Runs" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "description": "Run identifier" } ], "responses": { "200": { "description": "Run returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "status": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string" }, "progress": { "type": "number" }, "created_at": { "type": "number" }, "started_at": { "type": "number" }, "completed_at": { "type": "number" }, "error_code": { "type": "string", "description": "Machine-readable run error code", "examples": [ "provider_error" ] }, "error_message": { "type": "string", "description": "Human-readable run error message", "examples": [ "The provider failed to complete the generation." ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "output_id": { "type": "string", "description": "Run output identifier", "examples": [ "output_1" ] }, "type": { "enum": [ "imageUrl", "videoUrl", "audioUrl", "text", "documentUrl" ], "type": "string", "description": "Run output media type" }, "url": { "type": "string", "format": "uri", "description": "Run output URL", "examples": [ "https://media.flora.ai/output.png" ] } }, "required": [ "output_id", "type", "url" ] } }, "poll_url": { "type": "string", "format": "uri" } }, "required": [ "run_id", "status", "progress", "created_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/runs/action": { "post": { "operationId": "createActionRun", "summary": "Start an action run", "description": "Starts a headless prebuilt action run using raw action slugs such as rotate-image. Direct action runs do not create or mutate canvas nodes. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Runs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action_id", "workspace_id", "project_id", "inputs" ], "additionalProperties": false, "properties": { "action_id": { "description": "Action identifier. Use raw action slugs, not action-prefixed IDs.", "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string" }, "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "project_id": { "type": "string", "description": "Project identifier used for ownership, billing, and run history. Direct action runs do not mutate the project canvas.", "examples": [ "prj_abc123" ] }, "inputs": { "type": "array", "description": "Action inputs. Direct action runs are headless and read inputs from URLs/text rather than canvas edges.", "minItems": 1, "items": { "type": "object", "required": [ "type" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio", "text" ] }, "url": { "type": "string", "format": "uri", "description": "Input media URL" }, "text": { "type": "string", "description": "Input text value" }, "name": { "type": "string", "description": "Optional input name" } } } }, "params": { "type": "object", "description": "Action parameters", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Action run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "type": { "enum": [ "generation", "technique", "action" ], "type": "string", "description": "Run type" }, "model": { "anyOf": [ { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] } }, "required": [ "model_id" ] }, { "type": "null" } ] }, "technique": { "anyOf": [ { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name" } }, "required": [ "technique_id", "name" ] }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] } }, "required": [ "action_id" ] }, { "type": "null" } ] }, "estimated_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "poll_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "run_id", "type", "estimated_seconds", "charged_cost" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/runs/generation": { "post": { "operationId": "createGenerationRun", "summary": "Start a generation run", "description": "Starts a model generation run in a project canvas using a prompt, workspace, project, optional model, and optional model parameters. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "deprecated": true, "tags": [ "Runs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "prompt", "workspace_id", "project_id" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio", "text" ], "description": "Generation type" }, "prompt": { "type": "string", "minLength": 1, "description": "Generation prompt", "examples": [ "A cinematic product photo of a ceramic mug on a sunlit table" ] }, "model": { "type": "string", "description": "Model endpoint ID", "examples": [ "t2i-flux-2-pro" ] }, "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "project_id": { "type": "string", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "params": { "type": "object", "description": "Model parameters", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Generation run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "type": { "enum": [ "generation", "technique", "action" ], "type": "string", "description": "Run type" }, "model": { "anyOf": [ { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] } }, "required": [ "model_id" ] }, { "type": "null" } ] }, "technique": { "anyOf": [ { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name" } }, "required": [ "technique_id", "name" ] }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] } }, "required": [ "action_id" ] }, { "type": "null" } ] }, "estimated_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "poll_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "run_id", "type", "estimated_seconds", "charged_cost" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/runs/technique": { "post": { "operationId": "createTopLevelTechniqueRun", "summary": "Start a top-level technique run", "description": "Starts a technique run through the normalized top-level run resource. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Runs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "technique_id", "workspace_id", "inputs" ], "additionalProperties": false, "properties": { "technique_id": { "type": "string", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "inputs": { "type": "object", "description": "Technique inputs", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Technique run started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "type": { "enum": [ "generation", "technique", "action" ], "type": "string", "description": "Run type" }, "model": { "anyOf": [ { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] } }, "required": [ "model_id" ] }, { "type": "null" } ] }, "technique": { "anyOf": [ { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name" } }, "required": [ "technique_id", "name" ] }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] } }, "required": [ "action_id" ] }, { "type": "null" } ] }, "estimated_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "poll_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "run_id", "type", "estimated_seconds", "charged_cost" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}/nodes": { "get": { "operationId": "listCanvasNodes", "summary": "List project canvas nodes", "description": "Returns sanitized visible media nodes on a project canvas. The response omits raw graph documents, Liveblocks internals, raw Convex IDs, and unbounded node data blobs.", "tags": [ "Canvas" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of results to return" }, "allowEmptyValue": true, "allowReserved": true, "description": "Maximum number of results to return" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque cursor for fetching the next page" } ], "responses": { "200": { "description": "Canvas nodes returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "canvas_url": { "type": "string", "format": "uri", "description": "Project canvas URL" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "node_id": { "type": "string", "minLength": 1, "description": "Canvas node identifier", "examples": [ "node_abc123" ] }, "type": { "enum": [ "image", "video", "audio", "text" ], "type": "string", "description": "Canvas node media type" }, "label": { "anyOf": [ { "type": "string", "description": "Canvas node label", "examples": [ "Logo" ] }, { "type": "null" } ], "description": "Canvas node label" }, "asset_id": { "anyOf": [ { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, { "type": "null" } ], "description": "Asset identifier" }, "url": { "anyOf": [ { "type": "string", "minLength": 1, "description": "Canvas node output URL or text content", "examples": [ "https://media.flora.ai/output.png" ] }, { "type": "null" } ], "description": "Canvas node output URL or text content" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "node_id", "type" ] } }, "meta": { "type": "object", "properties": { "next_cursor": { "anyOf": [ { "type": "string", "description": "Opaque cursor for fetching the next page", "examples": [ "eyJvZmZzZXQiOjIwfQ" ] }, { "type": "null" } ], "description": "Opaque cursor for fetching the next page" }, "total_estimate": { "anyOf": [ { "type": "integer", "minimum": 0, "description": "Estimated total matching items" }, { "type": "null" } ], "description": "Estimated total matching items" } }, "required": [ "next_cursor" ] } }, "required": [ "project_id", "canvas_url", "nodes", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/projects/{projectId}/assets/{assetId}/attach": { "post": { "operationId": "attachCanvasAsset", "summary": "Attach an asset to a canvas", "description": "Attaches an existing ready asset to a project canvas as a static media node. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Canvas" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "description": "Project identifier" }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "description": "Asset identifier" } ], "responses": { "201": { "description": "Asset attached to canvas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "asset_id": { "type": "string", "pattern": "^asset_\\S+$", "description": "Asset identifier", "examples": [ "asset_abc123" ] }, "node_id": { "type": "string", "minLength": 1, "description": "Canvas node identifier", "examples": [ "node_abc123" ] }, "canvas_url": { "type": "string", "format": "uri", "description": "Project canvas URL" } }, "required": [ "project_id", "asset_id", "node_id", "canvas_url" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/feedback": { "post": { "operationId": "recordFeedback", "summary": "Record product feedback", "description": "Records product feedback from the authenticated user, optionally linked to a workspace, project, run, and attempted tools. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Feedback" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "feature_request", "bug", "technique_request", "missing_capability" ], "type": "string", "description": "Feedback kind" }, "summary": { "type": "string", "minLength": 1, "description": "Short summary", "examples": [ "Need batch export support" ] }, "detail": { "type": "string", "minLength": 1, "description": "Detailed description", "examples": [ "I want to export all generated campaign images at once." ] }, "attempted_tools": { "type": "array", "items": { "type": "string", "description": "Attempted tool name", "examples": [ "generate_image" ] }, "description": "Tools or capabilities attempted before submitting feedback" }, "workspace_id": { "type": "string", "pattern": "^ws_\\S+$", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "project_id": { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] } }, "required": [ "kind", "summary", "detail" ] } } } }, "responses": { "201": { "description": "Feedback recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_id": { "type": "string", "pattern": "^fb_\\S+$", "description": "Feedback identifier", "examples": [ "fb_abc123" ] }, "received_at": { "type": "integer" } }, "required": [ "feedback_id", "received_at" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } }, "/generate": { "post": { "operationId": "startGeneration", "summary": "Start a generation", "description": "Starts a model generation using a prompt, workspace, project, optional model, and optional model parameters. Poll the returned run_id via GET /runs/{runId} for progress and outputs. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.", "tags": [ "Generations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "prompt", "workspace_id", "project_id" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio", "text" ], "description": "Generation type" }, "prompt": { "type": "string", "minLength": 1, "description": "Generation prompt", "examples": [ "A cinematic product photo of a ceramic mug on a sunlit table" ] }, "model": { "type": "string", "description": "Model endpoint ID", "examples": [ "t2i-flux-2-pro" ] }, "workspace_id": { "type": "string", "description": "Workspace identifier", "examples": [ "ws_abc123" ] }, "project_id": { "type": "string", "description": "Project identifier", "examples": [ "prj_abc123" ] }, "params": { "type": "object", "description": "Model parameters", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Generation started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^run_\\S+$", "description": "Run identifier", "examples": [ "run_abc123" ] }, "type": { "enum": [ "generation", "technique", "action" ], "type": "string", "description": "Run type" }, "model": { "anyOf": [ { "type": "object", "properties": { "model_id": { "type": "string", "minLength": 1, "description": "Model identifier", "examples": [ "t2i-flux-2-pro" ] } }, "required": [ "model_id" ] }, { "type": "null" } ] }, "technique": { "anyOf": [ { "type": "object", "properties": { "technique_id": { "type": "string", "pattern": "^tech_\\S+$", "description": "Technique identifier", "examples": [ "tech_abcd1234" ] }, "name": { "type": "string", "description": "Technique name" } }, "required": [ "technique_id", "name" ] }, { "type": "null" } ] }, "action": { "anyOf": [ { "type": "object", "properties": { "action_id": { "enum": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ], "type": "string", "description": "Action identifier", "examples": [ "split-text", "find-and-replace-text", "concat-text", "ken-burns-video", "color-grade-image", "change-image-ar", "rotate-image", "flip-image", "color-filter-image", "color-tint-image", "filter-color-image", "blur-image", "duplicate-image", "side-by-side-composite", "add-shape-to-image", "generate-shape-image", "add-text-to-image", "generate-text-image", "qr-code-generator", "stitch-videos", "split-video", "extract-video-frames", "color-grade-video", "video-to-frame-grid", "boomerang-video", "reverse-video", "video-to-long-exposure", "video-effect", "color-filter-video", "speed-up-video", "slow-down-video", "duplicate-video", "greenscreen-video", "resize-video", "change-video-ar", "split-audio-from-video", "merge-audio-into-video" ] } }, "required": [ "action_id" ] }, { "type": "null" } ] }, "estimated_seconds": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "charged_cost": { "type": "number", "minimum": 0, "description": "Cost charged in USD" }, "poll_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "pattern": "^prj_\\S+$", "description": "Project identifier", "examples": [ "prj_abc123" ] }, { "type": "null" } ], "description": "Project identifier" } }, "required": [ "run_id", "type", "estimated_seconds", "charged_cost" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "input_validation_error": { "summary": "Invalid request", "value": { "error": { "code": "input_validation_error", "message": "prompt: Required", "fields": [ { "field": "prompt", "message": "Required" } ] } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unauthorized": { "summary": "Unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid API key." } } } } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "insufficient_credits": { "summary": "Insufficient credits", "value": { "error": { "code": "insufficient_credits", "message": "Insufficient credits." } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "forbidden": { "summary": "Forbidden", "value": { "error": { "code": "forbidden", "message": "Forbidden." } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "not_found": { "summary": "Not found", "value": { "error": { "code": "not_found", "message": "Not found." } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "idempotency_duplicate": { "summary": "Conflict", "value": { "error": { "code": "idempotency_duplicate", "message": "Duplicate idempotency key." } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "rate_limited": { "summary": "Rate limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded." } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_api_key", "forbidden", "invalid_json", "input_validation_error", "not_found", "insufficient_credits", "idempotency_duplicate", "rate_limited", "unknown_error" ], "examples": [ "input_validation_error" ] }, "message": { "type": "string", "examples": [ "name: Required" ] }, "fields": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "name" ] }, "message": { "type": "string", "examples": [ "Required" ] } } } } } } } }, "examples": { "unknown_error": { "summary": "Unknown error", "value": { "error": { "code": "unknown_error", "message": "An unknown error occurred." } } } } } } } } } } } }