{ "openapi": "3.1.0", "info": { "title": "Varibly Developer API", "version": "1.0.0", "description": "Programmatic access to Varibly — create projects, manage assets, generate AI ad creatives, and export them as images or videos. Authenticate every request with a Bearer API key from your account settings." }, "servers": [ { "url": "https://api.varibly.com", "description": "Production" }, { "url": "http://localhost:8080", "description": "Local development" } ], "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (vb_live_...)", "description": "API keys are created in your account settings. Send as `Authorization: Bearer vb_live_...`." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid_request" }, "message": { "type": "string", "example": "project_id is required." }, "details": { "type": "object", "additionalProperties": true, "nullable": true } }, "required": [ "code", "message" ] } } }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "generating", "complete" ] }, "knowledge_base": { "type": "string" }, "target_audiences": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "tones": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "cta_options": { "type": "array", "items": { "type": "string" } }, "brand_colors": { "type": "object", "additionalProperties": true }, "font_config": { "type": "object", "additionalProperties": true }, "creative_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } }, "resolutions": { "type": "array", "items": { "type": "string" } }, "credits_used": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "name", "status" ] }, "Creative": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "content": { "type": "object", "additionalProperties": true }, "overrides": { "type": "object", "additionalProperties": true }, "resolution": { "type": "string" }, "exported_image_url": { "type": "string", "nullable": true }, "exported_video_url": { "type": "string", "nullable": true }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "project_id", "content" ] }, "Asset": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string", "nullable": true }, "filename": { "type": "string" }, "file_url": { "type": "string" }, "file_type": { "type": "string" }, "file_size": { "type": "integer" }, "label": { "type": "string", "nullable": true }, "alt_text": { "type": "string", "nullable": true }, "dimensions": { "type": "object", "nullable": true, "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "filename", "file_url", "file_type" ] }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "usage", "purchase", "bonus", "refund" ] }, "credits": { "type": "integer" }, "amount_cents": { "type": "integer", "nullable": true }, "description": { "type": "string" }, "project_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ExportJob": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "complete", "failed", "cancelled" ] }, "progress": { "type": "integer", "nullable": true, "description": "For status=\"processing\": 0-100 frame-loop progress." }, "output_url": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "queue_position": { "type": "integer", "description": "1-indexed position among THIS USER\\u2019s active jobs." }, "queue_size": { "type": "integer", "description": "Total active jobs (queued + processing) for this user." }, "eta_seconds": { "type": "integer", "description": "Wall-clock seconds until completion. Reflects all queued+processing jobs globally divided by renderer concurrency, plus the job\\u2019s own remaining time." }, "estimated_start_at": { "type": "string", "format": "date-time", "nullable": true }, "estimated_complete_at": { "type": "string", "format": "date-time", "nullable": true }, "queue_state": { "type": "object", "description": "Aggregate render-queue context (opaque counts).", "properties": { "global_active": { "type": "integer" }, "global_queued": { "type": "integer" }, "global_processing": { "type": "integer" } } } } }, "MeResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "string" }, "key_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer", "nullable": true }, "reset_at": { "type": "integer", "nullable": true } } }, "quotas": { "type": "object", "properties": { "credits_remaining": { "type": "integer" }, "first_compile_free_available": { "type": "boolean" } } }, "plan": { "type": "string", "description": "Subscription tier or \"pay_as_you_go\"." }, "pricing": { "type": "object", "properties": { "blueprint_compile": { "type": "integer", "description": "Credits to compile a blueprint in default platform mode." }, "blueprint_compile_custom": { "type": "integer", "description": "Credits to compile a blueprint in custom mode (~37% higher LLM cost — full art-directed CSS)." }, "blueprint_refine": { "type": "integer", "description": "Credits to refine a platform-mode blueprint." }, "blueprint_refine_custom": { "type": "integer", "description": "Credits to refine a custom-mode blueprint." }, "animation_compile": { "type": "integer" }, "image_render": { "type": "integer" }, "video_render": { "type": "integer" } } } } } } }, "ProjectListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } }, "ProjectResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } } }, "ProjectDetailResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/Creative" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "knowledge_base": { "type": "string" }, "target_audiences": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "tones": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "cta_options": { "type": "array", "items": { "type": "string" } }, "brand_colors": { "type": "object", "additionalProperties": true }, "font_config": { "type": "object", "additionalProperties": true }, "creative_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } }, "resolutions": { "type": "array", "items": { "type": "string" } } } }, "UpdateProjectRequest": { "type": "object", "additionalProperties": true, "description": "Partial update. Any subset of CreateProjectRequest fields." }, "DeleteResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } } } } }, "StartGenerationRequest": { "type": "object", "required": [ "creative_count", "categories" ], "properties": { "creative_count": { "type": "integer", "minimum": 1, "maximum": 100 }, "categories": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "resolutions": { "type": "array", "items": { "type": "string" } }, "visual_types": { "type": "array", "items": { "type": "string" } } } }, "StartGenerationResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string" }, "estimated_seconds": { "type": "integer" }, "credits_charged": { "type": "integer" }, "mode": { "type": "string", "enum": [ "queued", "synchronous" ] } } } } }, "GenerationStatusResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "generating", "complete" ] }, "progress": { "type": "integer" }, "creatives_generated": { "type": "integer" }, "total_creatives": { "type": "integer" } } } } }, "CreativeListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/Creative" } } } } } }, "CreativeResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creative": { "$ref": "#/components/schemas/Creative" } } } } }, "UpdateCreativeRequest": { "type": "object", "required": [ "overrides" ], "properties": { "overrides": { "type": "object", "additionalProperties": true } } }, "FavoriteResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "is_favorite": { "type": "boolean" } } } } }, "AssetListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } }, "AssetResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Asset" } } } } }, "CreateAssetRequest": { "type": "object", "required": [ "filename", "file_type" ], "properties": { "project_id": { "type": "string", "nullable": true }, "filename": { "type": "string" }, "file_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ] }, "file_size": { "type": "integer" }, "label": { "type": "string" }, "alt_text": { "type": "string" }, "dimensions": { "type": "object", "additionalProperties": true } } }, "UpdateAssetRequest": { "type": "object", "properties": { "label": { "type": "string", "nullable": true }, "alt_text": { "type": "string", "nullable": true }, "project_id": { "type": "string", "nullable": true } } }, "CreateAssetResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Asset" }, "upload_url": { "type": "string", "description": "Signed URL — PUT the file bytes here within 15 minutes." } } } } }, "ExportImagesRequest": { "type": "object", "required": [ "project_id", "creative_ids" ], "properties": { "project_id": { "type": "string" }, "creative_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50 } } }, "ExportVideosRequest": { "type": "object", "required": [ "project_id", "creative_ids" ], "properties": { "project_id": { "type": "string" }, "creative_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50 }, "animation_preset": { "type": "string", "enum": [ "fade", "slide", "zoom" ], "default": "fade" }, "duration_seconds": { "type": "integer", "minimum": 3, "maximum": 15, "default": 5 } } }, "ExportJobsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_ids": { "type": "array", "items": { "type": "string" } }, "credits_charged": { "type": "integer" }, "queued": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "ExportJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ExportJob" } } }, "ExportDownloadResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Time-limited signed download URL." }, "expires_in_seconds": { "type": "integer" } } } } }, "CreditBalanceResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "credits": { "type": "integer" } } } } }, "CreditTransactionsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } }, "StatementPeriod": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "bucket": { "type": "string", "enum": [ "day", "week", "month" ] }, "total_credits_charged": { "type": "integer" }, "total_credits_added": { "type": "integer" }, "transaction_count": { "type": "integer" }, "by_type": { "type": "object", "additionalProperties": { "type": "object", "properties": { "credits": { "type": "integer" }, "cents": { "type": "integer" }, "count": { "type": "integer" } } } } } }, "CreditStatementsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "statements": { "type": "array", "items": { "$ref": "#/components/schemas/StatementPeriod" } } } } } }, "BudgetConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "monthly_cap_credits": { "type": "integer", "nullable": true }, "mode": { "type": "string", "enum": [ "hard", "soft" ], "description": "hard: block charges that exceed cap. soft: charge through, fire alert." }, "alert_thresholds": { "type": "array", "items": { "type": "integer" }, "description": "Percentages of cap (e.g. [50, 80, 100]) at which to fire alert events." } } }, "PeriodSpend": { "type": "object", "properties": { "period": { "type": "string", "description": "YYYY-MM (UTC)." }, "account_credits": { "type": "integer" }, "by_key": { "type": "object", "additionalProperties": { "type": "integer" } }, "alerts_fired": { "type": "array", "items": { "type": "integer" } } } }, "BudgetResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "budget": { "$ref": "#/components/schemas/BudgetConfig" }, "current_period": { "$ref": "#/components/schemas/PeriodSpend" } } } } }, "KeyBudgetResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "budget": { "$ref": "#/components/schemas/BudgetConfig" }, "current_period_spend_for_key": { "type": "integer" } } } } }, "BudgetUpdateRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "monthly_cap_credits": { "type": "integer", "nullable": true, "description": "null = unlimited." }, "mode": { "type": "string", "enum": [ "hard", "soft" ] }, "alert_thresholds": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200 } } } }, "BudgetUpdateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "budget": { "$ref": "#/components/schemas/BudgetConfig" } } } } }, "ContentSchemaField": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "longtext", "integer", "image", "list", "enum" ] }, "required": { "type": "boolean" }, "max_chars": { "type": "integer" }, "max_items": { "type": "integer" }, "enum_values": { "type": "array", "items": { "type": "string" } }, "item_schema": { "type": "object", "additionalProperties": true }, "recommended_mode": { "type": "string", "enum": [ "background", "hero-top", "hero-bottom", "contained", "side-left", "side-right", "none" ], "description": "Image-only render hint. Tells the platform CSS layer which image_mode to use for this slot at compile time. The binder may inject a runtime override if the actual asset disagrees with this hint." } } }, "ContentSchema": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContentSchemaField" } } } }, "AnimationSpec": { "type": "object", "required": [ "duration_seconds", "fps", "elements" ], "properties": { "duration_seconds": { "type": "number" }, "fps": { "type": "integer" }, "elements": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "opacity": { "type": "number" }, "transform": { "type": "string" }, "filter": { "type": "string" } } } } } } }, "BlueprintRenderRequest": { "type": "object", "required": [ "content", "format" ], "description": "Either blueprint_id (referencing a stored compiled blueprint) OR an inline blueprint must be provided. Resolution defaults to the blueprint\\u2019s compile-time resolution_label; override sparingly.", "properties": { "blueprint_id": { "type": "string", "description": "ID of a previously compiled blueprint. Mutually exclusive with the inline `blueprint` field." }, "blueprint": { "type": "object", "description": "Inline blueprint definition. Use blueprint_id instead for compiled blueprints.", "properties": { "html": { "type": "string", "description": "Bundle body markup with tags." }, "css": { "type": "string" }, "content_schema": { "$ref": "#/components/schemas/ContentSchema" }, "resolution_label": { "type": "string", "description": "Required for inline blueprints. One of GET /api/v1/resolutions." } } }, "resolution_label": { "type": "string", "description": "Optional override. Defaults to the blueprint\\u2019s compile-time label. Custom { width, height } not accepted." }, "content": { "type": "object", "additionalProperties": true, "description": "Map of slot name → value, validated against content_schema." }, "brand_kit": { "type": "object", "properties": { "colors": { "type": "object", "additionalProperties": { "type": "string" } }, "fonts": { "type": "object", "properties": { "headline": { "type": "string" }, "body": { "type": "string" }, "mono": { "type": "string" } } }, "spacing": { "type": "object", "properties": { "tight": { "type": "string" }, "normal": { "type": "string" }, "loose": { "type": "string" } } } } }, "format": { "type": "string", "enum": [ "png", "mp4" ] }, "animation_preset": { "type": "string", "enum": [ "fade", "slide", "zoom" ], "description": "Mp4-only entry-animation preset. Mutually exclusive with animation_spec and animation_id." }, "animation_spec": { "$ref": "#/components/schemas/AnimationSpec", "description": "Inline AnimationSpec for power users. Mp4-only. Mutually exclusive with animation_preset and animation_id." }, "animation_id": { "type": "string", "description": "Reference to a compiled animation (POST /api/v1/animations/compile). Mp4-only. Mutually exclusive with animation_preset and animation_spec." }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "For mp4 renders. Auto-clamps to the placement's `max_duration_seconds` (see GET /api/v1/resolutions). Omit to use the placement's `recommended_duration_seconds`. Global cap: 60s. yt_bumper requires exactly 6s. Must equal the animation_spec/animation_id duration when those are used." }, "composition": { "type": "string" } } }, "BlueprintRenderResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "format": { "type": "string", "enum": [ "png", "mp4" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "complete" ] }, "poll_url": { "type": "string" }, "download_url": { "type": "string" }, "image_url": { "type": "string", "description": "Populated for synchronous PNG renders that completed within the SLA." }, "signed_download_url": { "type": "string", "description": "Same as image_url. Use the download_url to refetch later." }, "duration_seconds": { "type": "integer", "description": "Effective video duration the renderer used (after per-placement clamping). Only present for mp4 renders." }, "duration_warning": { "type": "string", "description": "Set when the requested duration was auto-clamped to the placement's max (e.g. \"duration_seconds clamped from 90s to 60s\")." } } } } }, "CompileBlueprintRequest": { "type": "object", "required": [ "directive", "content_schema", "resolution_label" ], "properties": { "directive": { "type": "string", "description": "Natural-language design brief. Be specific — typography, layout, color, mood. Max 4000 chars.", "maxLength": 4000 }, "content_schema": { "$ref": "#/components/schemas/ContentSchema" }, "resolution_label": { "type": "string", "description": "One of the platform labels from GET /api/v1/resolutions (e.g. \"ig_story\", \"ig_feed_square\", \"fb_feed_landscape\", \"yt_shorts\", \"li_sponsored\"). Custom dimensions are not accepted — the catalog is curated for design quality." }, "project_id": { "type": "string", "description": "Optional. When set, the compiler auto-loads the project\\u2019s brand_colors, font_config, primary tone, and KB excerpt as design context. Eliminates the need to set up a brand_kit separately." }, "brand_kit_id": { "type": "string", "nullable": true, "description": "Optional brand kit. Wins over project_id-derived brand tokens if both supplied." }, "style_mode": { "type": "string", "enum": [ "platform", "custom" ], "description": "How the bundle inherits platform styling. `platform` (default, 10 credits) prepends a hand-tuned image-positioning + composition CSS layer that the bundle CSS layers on top of — best for high-quality renders out of the box. `custom` (14 credits) produces no platform CSS and lets the LLM author the entire stylesheet — use for art-directed / brutalist / experimental designs. The price difference reflects ~37% higher LLM output token cost." }, "anim_targets": { "type": "array", "description": "Optional decorative animatable elements to include in the bundle. Each one gets emitted with a stable [data-anim-target=\"\"] attribute. Used by AnimationSpec to choreograph motion (arrows drawing in, badges scale-popping, etc.). The compiler emits arrows/connectors as inline SVG with pathLength=\"1\".", "items": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "description": "Identifier matching [a-zA-Z_][a-zA-Z0-9_]*. Becomes the data-anim-target attribute and a logical selector in AnimationSpec." }, "kind": { "type": "string", "enum": [ "arrow", "connector", "badge", "shape", "highlight" ], "description": "Tells the compiler what kind of element to emit and how to style it." }, "description": { "type": "string", "description": "Optional free-form hint, e.g. \"connects hero to product image\"." } } } } } }, "AnimTargetDef": { "type": "object", "required": [ "name", "kind", "selector" ], "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "arrow", "connector", "badge", "shape", "highlight" ] }, "selector": { "type": "string", "description": "CSS selector targeting this element, e.g. [data-anim-target=\"arrow1\"]." } } }, "CompileAnimationRequest": { "type": "object", "required": [ "blueprint_id", "motion_directive", "duration_seconds" ], "properties": { "blueprint_id": { "type": "string", "description": "The blueprint whose slot + anim_target manifest defines the addressable surface." }, "motion_directive": { "type": "string", "maxLength": 4000, "description": "Plain-language choreography: \"Hero fades in. Then arrow draws to product over 1s. Then product scales up.\"" }, "duration_seconds": { "type": "number", "minimum": 0.1, "maximum": 60, "description": "Total length of the spec. The render call must request the same duration." }, "fps": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Frames per second. Defaults to 24." } } }, "CompileAnimationResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "animation": { "$ref": "#/components/schemas/Animation" }, "cache_hit": { "type": "boolean" }, "credits_charged": { "type": "integer" } } } } }, "Animation": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "user", "system" ] }, "directive": { "type": "string", "description": "The motion directive that produced this spec." }, "blueprint_id": { "type": "string", "nullable": true, "description": "The blueprint this animation was authored against." }, "spec": { "$ref": "#/components/schemas/AnimationSpec" }, "preview_url": { "type": "string", "nullable": true }, "cache_hash": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AnimationListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "animations": { "type": "array", "items": { "$ref": "#/components/schemas/Animation" } } } } } }, "AnimationResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "animation": { "$ref": "#/components/schemas/Animation" } } } } }, "ResolutionMeta": { "type": "object", "properties": { "label": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "platform": { "type": "string" }, "use_case": { "type": "string" }, "aspect": { "type": "string", "enum": [ "vertical", "square", "landscape", "banner", "skyscraper" ] }, "max_duration_seconds": { "type": "integer", "nullable": true, "description": "Hard maximum video duration accepted at this placement. null = static-image-only placement (mp4 not supported)." }, "recommended_duration_seconds": { "type": "integer", "nullable": true, "description": "Recommended duration for ad performance. Used as the default when /render is called without duration_seconds." } } }, "ResolutionsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "resolutions": { "type": "array", "items": { "$ref": "#/components/schemas/ResolutionMeta" } } } } } }, "BrandContextResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brand_context": { "type": "object", "properties": { "project_id": { "type": "string" }, "knowledge_base": { "type": "string" }, "target_audiences": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "tones": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "cta_options": { "type": "array", "items": { "type": "string" } }, "brand_colors": { "type": "object", "additionalProperties": true, "nullable": true }, "fonts": { "type": "object", "properties": { "headline": { "type": "string", "nullable": true }, "body": { "type": "string", "nullable": true } } } } } } } } }, "Blueprint": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "user", "system" ] }, "directive": { "type": "string" }, "refined_from": { "type": "string", "nullable": true }, "content_schema": { "$ref": "#/components/schemas/ContentSchema" }, "slot_manifest": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "image", "list", "repeating" ] }, "selector": { "type": "string" }, "occurrences": { "type": "integer" } } } }, "anim_target_manifest": { "type": "array", "description": "Decorative animatable elements emitted in the bundle (one entry per declared anim_target). AnimationSpec selectors may reference these names alongside slot names.", "items": { "$ref": "#/components/schemas/AnimTargetDef" } }, "resolution_default": { "type": "string" }, "animation_default_id": { "type": "string", "nullable": true }, "brand_kit_id": { "type": "string", "nullable": true }, "preview_url": { "type": "string", "nullable": true }, "cache_hash": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "compiling", "ready", "failed" ] }, "style_mode": { "type": "string", "enum": [ "platform", "custom" ], "description": "Style mode used to compile this bundle. `platform` bundles get the platform image-positioning CSS prepended at render time." }, "failure_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "html": { "type": "string", "description": "Bundle HTML — only returned with ?include_source=true on owned blueprints." }, "css": { "type": "string", "description": "Bundle CSS — only returned with ?include_source=true on owned blueprints." } } }, "RefineBlueprintRequest": { "type": "object", "required": [ "directive" ], "properties": { "directive": { "type": "string", "description": "Refinement instruction (e.g. \"make the accent stripe gradient instead of solid\"). Max 2000 chars.", "maxLength": 2000 } } }, "BlueprintPreviewRequest": { "type": "object", "properties": { "content": { "type": "object", "additionalProperties": true, "description": "Content to bind into the blueprint slots. Same shape as render content." }, "resolution_label": { "type": "string", "description": "Optional override of the blueprint's compile-time resolution." } } }, "BlueprintPreviewResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "html": { "type": "string", "description": "Bound HTML with vb://asset/* references resolved to data URLs." }, "width": { "type": "integer" }, "height": { "type": "integer" }, "style_mode": { "type": "string", "enum": [ "platform", "custom" ] }, "slot_manifest": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "RenderBatchRequest": { "type": "object", "required": [ "variants", "format" ], "description": "Same shape as POST /api/v1/render but `variants` is an array of content objects. All other fields apply to every variant.", "properties": { "blueprint_id": { "type": "string" }, "blueprint": { "type": "object", "additionalProperties": true }, "variants": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 50, "description": "Each item is a content map for that variant." }, "format": { "type": "string", "enum": [ "png", "mp4" ] }, "animation_preset": { "type": "string", "enum": [ "fade", "slide", "zoom" ] }, "duration_seconds": { "type": "integer" }, "resolution_label": { "type": "string" }, "brand_kit": { "type": "object", "additionalProperties": true } } }, "RenderBatchResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "variants": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "ok": { "type": "boolean" }, "job_id": { "type": "string" }, "error": { "type": "string" } } } }, "queued": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "JobsListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "complete", "failed", "cancelled" ] }, "kind": { "type": "string", "enum": [ "png", "mp4_short", "mp4_medium", "mp4_long" ], "description": "Render-kind classification (used for ETA math)." }, "format": { "type": "string", "enum": [ "png", "mp4" ] }, "progress": { "type": "integer", "nullable": true, "description": "For status=\"processing\": 0-100 frame-loop progress." }, "output_url": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "record_kind": { "type": "string", "enum": [ "blueprint", "creative" ], "description": "Whether the job was dispatched against a Tier 3 blueprint or a Tier 1/2 creative." }, "queue_position": { "type": "integer", "description": "1-indexed position among THIS USER\\u2019s active jobs, ordered by created_at. Other tenants\\u2019 jobs are not visible here." }, "queue_size": { "type": "integer", "description": "Total active jobs (queued + processing) for this user." }, "eta_seconds": { "type": "integer", "description": "Total wall-clock seconds until this job completes. Reflects ALL queued+processing jobs globally (across tenants), divided by renderer concurrency, plus the job\\u2019s own remaining time." }, "estimated_start_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO timestamp when this job is estimated to pick up a worker. Equals started_at if already running." }, "estimated_complete_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO timestamp when this job is estimated to finish." } } } }, "count": { "type": "integer" }, "queue_state": { "type": "object", "description": "Aggregate render-queue context. Opaque counts only; no per-tenant data leaks.", "properties": { "global_active": { "type": "integer", "description": "queued + processing across all tenants." }, "global_queued": { "type": "integer" }, "global_processing": { "type": "integer" } } } } } } }, "QueueStateResponse": { "type": "object", "description": "Aggregate render-queue health. Opaque counts only.", "properties": { "data": { "type": "object", "properties": { "queued": { "type": "integer" }, "processing": { "type": "integer" }, "active": { "type": "integer", "description": "queued + processing." }, "by_kind": { "type": "object", "additionalProperties": { "type": "object", "properties": { "active": { "type": "integer" }, "expected_ms": { "type": "integer", "description": "Heuristic mean render duration for this kind." } } } }, "effective_concurrency": { "type": "integer", "description": "Cloud Tasks max-concurrent-dispatches for video-render-queue." }, "oldest_queued_at": { "type": "string", "format": "date-time", "nullable": true }, "estimated_drain_seconds": { "type": "integer", "description": "Wall-clock seconds for the queue to fully drain at current concurrency, given current ahead-time." }, "estimated_drain_at": { "type": "string", "format": "date-time" }, "truncated": { "type": "boolean", "description": "True if the global-active scan hit its 500-job cap (rare; ETA fuzzy at the tail when so)." } } } } }, "CompileBlueprintResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blueprint": { "$ref": "#/components/schemas/Blueprint" }, "cache_hit": { "type": "boolean" }, "credits_charged": { "type": "integer" } } } } }, "BlueprintResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blueprint": { "$ref": "#/components/schemas/Blueprint" } } } } }, "BlueprintListResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blueprints": { "type": "array", "items": { "$ref": "#/components/schemas/Blueprint" } } } } } } } }, "security": [ { "BearerApiKey": [] } ], "paths": { "/api/v1/me": { "get": { "operationId": "getMe", "summary": "Identity, scopes, and rate-limit info for the calling key", "tags": [ "Me" ], "parameters": [], "security": [ { "BearerApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects": { "get": { "operationId": "listProjects", "summary": "List your projects", "tags": [ "Projects" ], "parameters": [], "security": [ { "BearerApiKey": [ "projects:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "tags": [ "Projects" ], "parameters": [], "security": [ { "BearerApiKey": [ "projects:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } } } }, "/api/v1/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get a project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "projects:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDetailResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateProject", "summary": "Update a project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "projects:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } } } }, "delete": { "operationId": "deleteProject", "summary": "Delete a project", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "projects:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{id}/brand-context": { "get": { "operationId": "getBrandContext", "summary": "Brand + KB context for the agent\\u2019s LLM to use when generating variants", "tags": [ "Projects" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "projects:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandContextResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{id}/generations": { "post": { "operationId": "startGeneration", "summary": "Start a creative generation job", "tags": [ "Generations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "generate:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGenerationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartGenerationRequest" } } } } } }, "/api/v1/projects/{id}/generations/latest": { "get": { "operationId": "getGenerationStatus", "summary": "Get latest generation status", "tags": [ "Generations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "projects:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationStatusResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{projectId}/creatives": { "get": { "operationId": "listCreatives", "summary": "List creatives in a project", "tags": [ "Creatives" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "creatives:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativeListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{projectId}/creatives/{id}": { "get": { "operationId": "getCreative", "summary": "Get a creative", "tags": [ "Creatives" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "creatives:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativeResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateCreative", "summary": "Update creative overrides", "tags": [ "Creatives" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "creatives:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativeResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCreativeRequest" } } } } }, "delete": { "operationId": "deleteCreative", "summary": "Delete a creative", "tags": [ "Creatives" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "creatives:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/projects/{projectId}/creatives/{id}/favorite": { "post": { "operationId": "toggleFavorite", "summary": "Toggle creative favorite", "tags": [ "Creatives" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "creatives:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/assets": { "get": { "operationId": "listAssets", "summary": "List assets", "tags": [ "Assets" ], "parameters": [], "security": [ { "BearerApiKey": [ "assets:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createAsset", "summary": "Create an asset (signed upload)", "tags": [ "Assets" ], "parameters": [], "security": [ { "BearerApiKey": [ "assets:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetRequest" } } } } } }, "/api/v1/assets/{id}": { "get": { "operationId": "getAsset", "summary": "Get an asset", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "assets:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateAsset", "summary": "Update asset metadata", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "assets:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetRequest" } } } } }, "delete": { "operationId": "deleteAsset", "summary": "Delete an asset", "tags": [ "Assets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "assets:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/exports/images": { "post": { "operationId": "exportImages", "summary": "Render selected creatives as PNGs", "tags": [ "Exports" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportImagesRequest" } } } } } }, "/api/v1/exports/videos": { "post": { "operationId": "exportVideos", "summary": "Render selected creatives as MP4s", "tags": [ "Exports" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportVideosRequest" } } } } } }, "/api/v1/exports/videos/{jobId}": { "get": { "operationId": "getExportStatus", "summary": "Get export job status", "tags": [ "Exports" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/exports/{id}/download": { "get": { "operationId": "getExportDownload", "summary": "Get signed download URL for export", "tags": [ "Exports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDownloadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/render": { "post": { "operationId": "renderBlueprint", "summary": "Render a blueprint bundle (PNG returns inline within ~30s SLA; MP4 returns job_id, poll for status)", "tags": [ "Render" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintRenderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintRenderRequest" } } } } } }, "/api/v1/resolutions": { "get": { "operationId": "listResolutions", "summary": "Catalog of platform resolutions accepted as resolution_label", "tags": [ "Discovery" ], "parameters": [], "security": [ { "BearerApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolutionsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/system/queue": { "get": { "operationId": "getQueueState", "summary": "Aggregate render-queue health: depth, concurrency, ETA-to-drain. Opaque counts only.", "tags": [ "Discovery" ], "parameters": [], "security": [ { "BearerApiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueStateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/blueprints/compile": { "post": { "operationId": "compileBlueprint", "summary": "Compile a blueprint from a directive (Tier 3)", "tags": [ "Blueprints" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileBlueprintResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileBlueprintRequest" } } } } } }, "/api/v1/blueprints": { "get": { "operationId": "listBlueprints", "summary": "List your blueprints", "tags": [ "Blueprints" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/blueprints/{id}": { "get": { "operationId": "getBlueprint", "summary": "Get a blueprint (?include_source=true returns html/css)", "tags": [ "Blueprints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteBlueprint", "summary": "Delete a blueprint", "tags": [ "Blueprints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/blueprints/{id}/refine": { "post": { "operationId": "refineBlueprint", "summary": "Refine an existing blueprint with a tweak directive (cheaper than full compile)", "tags": [ "Blueprints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileBlueprintResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefineBlueprintRequest" } } } } } }, "/api/v1/blueprints/{id}/fork": { "post": { "operationId": "forkBlueprint", "summary": "Fork an existing blueprint (system or owned) into your account, free", "tags": [ "Blueprints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileBlueprintResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/blueprints/{id}/preview": { "post": { "operationId": "previewBlueprint", "summary": "Bind content into the blueprint and return the resolved HTML/CSS without rendering. Useful for editable-export tools that walk the DOM and translate to native layers. Free.", "tags": [ "Blueprints" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreviewResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreviewRequest" } } } } } }, "/api/v1/animations/compile": { "post": { "operationId": "compileAnimation", "summary": "Compile a motion directive into a reusable AnimationSpec for a blueprint (Tier 3)", "tags": [ "Animations" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileAnimationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompileAnimationRequest" } } } } } }, "/api/v1/animations": { "get": { "operationId": "listAnimations", "summary": "List your compiled animations", "tags": [ "Animations" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimationListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/animations/{id}": { "get": { "operationId": "getAnimation", "summary": "Get a compiled animation (includes spec)", "tags": [ "Animations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnimationResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteAnimation", "summary": "Delete a compiled animation", "tags": [ "Animations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/renders/batch": { "post": { "operationId": "renderBatch", "summary": "Queue up to 50 renders for one blueprint with N content variants", "tags": [ "Render" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderBatchResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderBatchRequest" } } } } } }, "/api/v1/jobs": { "get": { "operationId": "listJobs", "summary": "List active render jobs (?status=active|terminal|queued|processing|complete|failed)", "tags": [ "Discovery" ], "parameters": [], "security": [ { "BearerApiKey": [ "export:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsListResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/credits/balance": { "get": { "operationId": "getCreditBalance", "summary": "Get credit balance", "tags": [ "Credits" ], "parameters": [], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/credits/transactions": { "get": { "operationId": "listCreditTransactions", "summary": "List credit transactions (?from, ?to, ?type, ?limit)", "tags": [ "Credits" ], "parameters": [], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditTransactionsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/credits/statements": { "get": { "operationId": "listCreditStatements", "summary": "Aggregated spend per period (?bucket=day|week|month, ?from, ?to)", "tags": [ "Credits" ], "parameters": [], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditStatementsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/account/budget": { "get": { "operationId": "getAccountBudget", "summary": "Get account-level budget config + current-period spend", "tags": [ "Budget" ], "parameters": [], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "setAccountBudget", "summary": "Set account-level monthly cap + alert thresholds + hard/soft mode", "tags": [ "Budget" ], "parameters": [], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdateRequest" } } } } } }, "/api/v1/account/api-keys/{id}/budget": { "get": { "operationId": "getKeyBudget", "summary": "Get per-key budget config", "tags": [ "Budget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyBudgetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "setKeyBudget", "summary": "Set per-key monthly cap (defense against rogue agents)", "tags": [ "Budget" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "BearerApiKey": [ "credits:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden (missing scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdateRequest" } } } } } } }, "tags": [ { "name": "Me", "description": "Identity & rate-limit introspection" }, { "name": "Projects", "description": "Brand-scoped containers for creatives and assets" }, { "name": "Generations", "description": "Async LLM generation jobs" }, { "name": "Creatives", "description": "Generated ad units within a project" }, { "name": "Assets", "description": "User-uploaded images for use in creatives" }, { "name": "Exports", "description": "Render creatives to PNG or MP4" }, { "name": "Render", "description": "Stateless render of a blueprint bundle (Tier 3)" }, { "name": "Blueprints", "description": "Tier 3 — AI-compiled HTML/CSS bundles for agentic flows" }, { "name": "Discovery", "description": "Catalogs (resolutions, scopes) for agent introspection" }, { "name": "Credits", "description": "Credit balance and usage history" }, { "name": "Budget", "description": "Spend caps, per-key budgets, alert thresholds — defense against runaway agents" } ] }