{"openapi":"3.0.0","info":{"title":"AdMove API","version":"2026-02-02","description":"API for managing workspaces, products, and creative assets"},"servers":[{"url":"https://api.admove.ai/","description":"Production API Server"}],"security":[{"APIKeyAuth":[]}],"components":{"schemas":{},"parameters":{},"securitySchemes":{"APIKeyAuth":{"type":"apiKey","in":"header","name":"X-AdMove-Key","description":"API key authentication. Use your API key in the X-AdMove-Key header. Example: \"X-AdMove-Key: sk_test_...\""}}},"paths":{"/v1/workspaces":{"get":{"summary":"List workspaces","description":"List workspaces accessible to the authenticated user","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"responses":{"200":{"description":"List of workspaces","content":{"application/json":{"schema":{"type":"object","properties":{"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"My Workspace"},"ownerId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"logo":{"type":"string","nullable":true,"example":"user-id/workspace-id/media/logo.png","description":"Storage path, not URL"},"productsSource":{"type":"object","nullable":true,"properties":{"name":{"type":"string","example":"My Products Source"},"description":{"type":"string","example":"My Products Source Description"},"url":{"type":"string","example":"https://example.com/products-source"},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["shopify","product_page"]},"language":{"type":"object","properties":{"isoCode":{"type":"string","example":"en"},"name":{"type":"string","example":"English"}},"required":["isoCode","name"]}},"required":["name","description","url","currency","type","language"]},"onboarding":{"type":"object","nullable":true,"properties":{"step":{"type":"string","enum":["welcome","goal-selection","store-setup","review-brand","pick-product","review-product-intelligence","generate","adset","complete"],"example":"welcome"},"workflowRunId":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4","description":"Workflow run ID"},"hookTokens":{"type":"object","additionalProperties":{"type":"string"},"example":{"step1":"123e4567-e89b-12d3-a456-426614174000","step2":"123e4567-e89b-12d3-a456-426614174000"}}},"required":["step","workflowRunId","hookTokens"]},"planName":{"type":"string","example":"Starter"}},"required":["id","name","ownerId","createdAt"],"description":"Workspace"}}},"required":["workspaces"],"description":"GetWorkspacesResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"post":{"summary":"Create workspace","description":"Create a new workspace. Send as multipart/form-data with name (required) and optional logo (image file).","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Workspace name"},"logo":{"type":"string","format":"binary","description":"Logo image file (PNG, SVG, JPG, or WebP)"}}}}}},"responses":{"201":{"description":"Workspace created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"My Workspace"},"ownerId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"logo":{"type":"string","nullable":true,"example":"user-id/workspace-id/media/logo.png","description":"Storage path, not URL"},"productsSource":{"type":"object","nullable":true,"properties":{"name":{"type":"string","example":"My Products Source"},"description":{"type":"string","example":"My Products Source Description"},"url":{"type":"string","example":"https://example.com/products-source"},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["shopify","product_page"]},"language":{"type":"object","properties":{"isoCode":{"type":"string","example":"en"},"name":{"type":"string","example":"English"}},"required":["isoCode","name"]}},"required":["name","description","url","currency","type","language"]},"onboarding":{"type":"object","nullable":true,"properties":{"step":{"type":"string","enum":["welcome","goal-selection","store-setup","review-brand","pick-product","review-product-intelligence","generate","adset","complete"],"example":"welcome"},"workflowRunId":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4","description":"Workflow run ID"},"hookTokens":{"type":"object","additionalProperties":{"type":"string"},"example":{"step1":"123e4567-e89b-12d3-a456-426614174000","step2":"123e4567-e89b-12d3-a456-426614174000"}}},"required":["step","workflowRunId","hookTokens"]},"planName":{"type":"string","example":"Starter"}},"required":["id","name","ownerId","createdAt"],"description":"Workspace"}},"required":["workspace"],"description":"CreateWorkspaceResponse"}}}},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}":{"get":{"summary":"Get workspace","description":"Get a single workspace by ID (requires access)","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Workspace details","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"My Workspace"},"ownerId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"logo":{"type":"string","nullable":true,"example":"user-id/workspace-id/media/logo.png","description":"Storage path, not URL"},"productsSource":{"type":"object","nullable":true,"properties":{"name":{"type":"string","example":"My Products Source"},"description":{"type":"string","example":"My Products Source Description"},"url":{"type":"string","example":"https://example.com/products-source"},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["shopify","product_page"]},"language":{"type":"object","properties":{"isoCode":{"type":"string","example":"en"},"name":{"type":"string","example":"English"}},"required":["isoCode","name"]}},"required":["name","description","url","currency","type","language"]},"onboarding":{"type":"object","nullable":true,"properties":{"step":{"type":"string","enum":["welcome","goal-selection","store-setup","review-brand","pick-product","review-product-intelligence","generate","adset","complete"],"example":"welcome"},"workflowRunId":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4","description":"Workflow run ID"},"hookTokens":{"type":"object","additionalProperties":{"type":"string"},"example":{"step1":"123e4567-e89b-12d3-a456-426614174000","step2":"123e4567-e89b-12d3-a456-426614174000"}}},"required":["step","workflowRunId","hookTokens"]},"planName":{"type":"string","example":"Starter"}},"required":["id","name","ownerId","createdAt"],"description":"Workspace"}},"required":["workspace"],"description":"GetWorkspaceResponse"}}}},"400":{"description":"Invalid workspace ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"patch":{"summary":"Update workspace","description":"Update workspace name and/or logo. Send as multipart/form-data with optional name (string) and logo (image file).","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Workspace name"},"logo":{"type":"string","format":"binary","description":"Logo image file (PNG, SVG, JPG, or WebP)"}}}}}},"responses":{"200":{"description":"Workspace updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"My Workspace"},"ownerId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"logo":{"type":"string","nullable":true,"example":"user-id/workspace-id/media/logo.png","description":"Storage path, not URL"},"productsSource":{"type":"object","nullable":true,"properties":{"name":{"type":"string","example":"My Products Source"},"description":{"type":"string","example":"My Products Source Description"},"url":{"type":"string","example":"https://example.com/products-source"},"currency":{"type":"string","example":"USD"},"type":{"type":"string","enum":["shopify","product_page"]},"language":{"type":"object","properties":{"isoCode":{"type":"string","example":"en"},"name":{"type":"string","example":"English"}},"required":["isoCode","name"]}},"required":["name","description","url","currency","type","language"]},"onboarding":{"type":"object","nullable":true,"properties":{"step":{"type":"string","enum":["welcome","goal-selection","store-setup","review-brand","pick-product","review-product-intelligence","generate","adset","complete"],"example":"welcome"},"workflowRunId":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4","description":"Workflow run ID"},"hookTokens":{"type":"object","additionalProperties":{"type":"string"},"example":{"step1":"123e4567-e89b-12d3-a456-426614174000","step2":"123e4567-e89b-12d3-a456-426614174000"}}},"required":["step","workflowRunId","hookTokens"]},"planName":{"type":"string","example":"Starter"}},"required":["id","name","ownerId","createdAt"],"description":"Workspace"}},"required":["workspace"],"description":"UpdateWorkspaceResponse"}}}},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"delete":{"summary":"Delete workspace","description":"Delete a workspace (owner only). Fails if workspace has completed onboarding and an active subscription, or if it is the last workspace.","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Workspace deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Bad request - cannot delete","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - not owner","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/brand":{"get":{"summary":"Get workspace brand","description":"Get brand information for a workspace (requires access)","security":[{"APIKeyAuth":[]}],"tags":["Brand"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Brand information (object or empty)","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"description":"BrandInformation"}},"required":["brand"],"description":"GetWorkspaceBrandResponse"}}}},"400":{"description":"Invalid workspace ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"patch":{"summary":"Update workspace brand","description":"Partially update brand (requires access). JSON only. For logos, use POST brand-logos.","security":[{"APIKeyAuth":[]}],"tags":["Brand"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}}},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"body":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}}}},"description":"PatchWorkspaceBrandRequest"}}}},"responses":{"200":{"description":"Updated brand information","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"description":"BrandInformation"}},"required":["brand"],"description":"GetWorkspaceBrandResponse"}}}},"400":{"description":"Invalid workspace ID or request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/brand-logos":{"post":{"summary":"Upload brand logos","description":"Upload logo files for workspace brand (requires access). Multipart with logos (files). Adds to existing logos. PNG, JPEG, SVG, WebP; max 5MB each.","security":[{"APIKeyAuth":[]}],"tags":["Brand"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"string","format":"binary"},"minItems":1,"description":"Logo image files (PNG, JPEG, SVG, WebP; max 5MB each). Send multiple with field name \"logos\"."}}}}}},"responses":{"200":{"description":"Brand with updated logos","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"description":"BrandInformation"}},"required":["brand"],"description":"GetWorkspaceBrandResponse"}}}},"400":{"description":"Invalid workspace ID or request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/brand-logos/{logoId}":{"delete":{"summary":"Delete brand logo","description":"Delete a logo by ID from workspace brand (requires access). Logo ID is the uuid returned when uploading.","security":[{"APIKeyAuth":[]}],"tags":["Brand"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"logoId","in":"path"}],"responses":{"200":{"description":"Brand with updated logos","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"description":"BrandInformation"}},"required":["brand"],"description":"GetWorkspaceBrandResponse"}}}},"400":{"description":"Invalid workspace ID or logo ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Logo not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/adsets":{"get":{"summary":"Get workspace adsets","description":"Get all adsets for a workspace, optionally filtered by product_id. Supports limit/offset pagination.","security":[{"APIKeyAuth":[]}],"tags":["Adsets"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":false,"name":"product_id","in":"query"},{"schema":{"type":"number","nullable":true,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of adsets","content":{"application/json":{"schema":{"type":"object","properties":{"adsets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Ad Set Name"},"status":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["generating_briefs","reviewing_briefs","generating_creatives","reviewing_creatives","rejected","errored","approved","scheduled_for_publish","published","inactive","paused","ended"]},"date":{"type":"string"}},"required":["type"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"title":{"type":"string","example":"Ad Title"},"status":{"type":"string","enum":["generating_brief","reviewing_brief","brief_rejected","generating_creative","reviewing_creative","creative_rejected","approved","errored"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"brief":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"personaId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","additionalProperties":{"nullable":true},"example":{}}},"required":["id","personaId","data"],"description":"Brief"}},"required":["id","title","status"],"description":"Ad"}}},"required":["id","name","ads"],"description":"AdSet"}},"total":{"type":"number","example":42}},"required":["adsets","total"],"description":"GetWorkspaceAdsetsResponse"}}}},"400":{"description":"Invalid workspace ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/source_products":{"get":{"summary":"Get source products","description":"List Shopify source products. Requires productsSource.type === \"shopify\".","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Shopify products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"handle":{"type":"string","example":"product-handle"},"body_html":{"type":"string"},"published_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"vendor":{"type":"string"},"product_type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"images":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"options":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["id","title","handle"],"description":"ShopifyProduct"}}},"required":["products"],"description":"GetWorkspaceSourceProductsResponse"}}}},"400":{"description":"Products source must be Shopify","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/source_urls":{"get":{"summary":"Get source URLs","description":"List source URLs via Firecrawl map. Requires productsSource.type === \"product_page\".","security":[{"APIKeyAuth":[]}],"tags":["Workspaces"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Array of { url }","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/page"}},"required":["url"],"description":"SourceUrlItem"},"description":"GetWorkspaceSourceUrlsResponse"}}}},"400":{"description":"Products source must be product_page","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/scrape-products":{"post":{"summary":"Start scrape products","description":"Start a product scraping workflow for the given URLs. Body: { workspaceId, urls }. Returns 202 with runId. Max 10 URLs.","security":[{"APIKeyAuth":[]}],"tags":["Scrape Products"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"urls":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"example":["https://example.com/product1","https://example.com/product2"]}},"required":["workspaceId","urls"],"description":"CreateScrapeProductsRequest"}}}},"responses":{"202":{"description":"Scrape job started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"status":{"type":"string","enum":["pending"],"example":"pending"},"createdAt":{"type":"string","example":"2026-02-12T12:00:00.000Z"}},"required":["id","status","createdAt"],"description":"CreateScrapeProductsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workspace not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/scrape-products/{id}":{"get":{"summary":"Get scrape products status","description":"Get scrape products workflow status and results (poll for completion). Looks up run by id.","security":[{"APIKeyAuth":[]}],"tags":["Scrape Products"],"parameters":[{"schema":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Scrape status and results","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"completed"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"handle":{"type":"string"},"description":{"type":"string"},"price":{"type":"string"},"compareAtPrice":{"type":"string"},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"src":{"type":"string"},"alt":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"src":{"type":"string"},"poster":{"type":"string","nullable":true},"alt":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","src","position"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"sku":{"type":"string"},"price":{"type":"string"},"compareAtPrice":{"type":"string"},"available":{"type":"boolean"}},"required":["id","title","sku","price","available"]}},"available":{"type":"boolean"}},"required":["id","title","handle","description","price","tags","images","videos","variants","available"],"description":"ScrapedProduct"}},"createdAt":{"type":"string","example":"2026-02-12T12:00:00.000Z"},"completedAt":{"type":"string","example":"2026-02-12T12:00:00.000Z"}},"required":["id","status","createdAt"],"description":"GetScrapeProductsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/generate-adsets":{"post":{"summary":"Start generate adsets","description":"Start the adset generation workflow. Body: { productId, images: [{concept, count}], videos: [{concept, count}], instructions? }. concept: \"any\" = AI selects; specific concept = pre-selected. Cannot mix \"any\" with specific concepts. Returns 202 with id (run id), adSetId, createdAt. Requires API key.","security":[{"APIKeyAuth":[]}],"tags":["Generate Adsets"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"images":{"type":"array","items":{"type":"object","properties":{"concept":{"type":"string","enum":["any","announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"]},"count":{"type":"integer","minimum":1}},"required":["concept","count"]},"minItems":0,"example":[{"concept":"product_spotlight","count":1},{"concept":"social_proof","count":1}]},"videos":{"type":"array","items":{"type":"object","properties":{"concept":{"type":"string","enum":["any","ugc","product_demo","explainer","vsl"]},"count":{"type":"integer","minimum":1}},"required":["concept","count"]},"minItems":0,"example":[{"concept":"ugc","count":1}]},"instructions":{"type":"string"}},"required":["productId","images","videos"],"description":"CreateGenerateAdsetsRequest"}}}},"responses":{"202":{"description":"Generate adsets job started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"adSetId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","example":"2026-02-12T12:00:00.000Z"}},"required":["id","adSetId","createdAt"],"description":"CreateGenerateAdsetsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product or brand not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/generate-adsets/{id}":{"put":{"summary":"Approve or reject briefs/creatives","description":"Approve or reject briefs/creatives for a workflow run. id = workflow run id from first response. Body: { mode: \"approve-briefs\" | \"approve-creatives\", adSetId, data: [{ adId, approved }] }. mode approve-briefs: rejected ads get brief_rejected; mode approve-creatives: rejected ads get creative_rejected. Requires API key.","security":[{"APIKeyAuth":[]}],"tags":["Generate Adsets"],"parameters":[{"schema":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["approve-briefs","approve-creatives"],"example":"approve-briefs","description":"approve-briefs: set rejected ads to brief_rejected; approve-creatives: set rejected ads to creative_rejected"},"adSetId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string","format":"uuid"},"approved":{"type":"boolean"}},"required":["adId","approved"]}}},"required":["mode","adSetId","data"],"description":"PutGenerateAdsetsRequest"}}}},"responses":{"200":{"description":"Briefs/creatives updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Run or adset not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/adsets/{id}/creatives":{"post":{"summary":"Start creative generation for manual adset","description":"Start creative generation for a manually created adset (one with briefs but no running workflow). Body: { data: [{ adId, approved }] }. Returns 202 with id (run id), adSetId, createdAt. Poll ad statuses via GET /api/v1/adsets/:adsetId. Requires API key.","security":[{"APIKeyAuth":[]}],"tags":["Adsets"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"adId":{"type":"string","format":"uuid"},"approved":{"type":"boolean"}},"required":["adId","approved"]}}},"required":["data"],"description":"CreateGenerateCreativesRequest"}}}},"responses":{"202":{"description":"Creative generation started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"adSetId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","example":"2026-02-12T12:00:00.000Z"}},"required":["id","adSetId","createdAt"],"description":"CreateGenerateCreativesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"AdSet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspaces/{id}/products":{"get":{"summary":"Get workspace products","description":"Get all products for a workspace (requires access)","security":[{"APIKeyAuth":[]}],"tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"description":{"type":"string","example":"Product description"},"vendor":{"type":"string","example":"Vendor Name"},"productType":{"type":"string","example":"Product Type"},"tags":{"type":"array","items":{"type":"string"},"example":["Tag 1","Tag 2"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Variant Name"},"sku":{"type":"string","example":"SKU123"},"price":{"type":"string","example":"100.00"},"compareAtPrice":{"type":"string","example":"120.00"},"available":{"type":"boolean","example":true}},"required":["id","title","sku","price","available"]}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/image.jpg"},"alt":{"type":"string","nullable":true,"example":"Image alt text"},"position":{"type":"number","example":1}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/video.mp4"},"poster":{"type":"string","example":"https://example.com/video.jpg"},"alt":{"type":"string","example":"Video alt text"},"position":{"type":"number","example":1}},"required":["id","src","poster","alt","position"]}},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"handle":{"type":"string","example":"product-name"},"sourceType":{"type":"string","enum":["shopify","woocommerce","product_page"]},"publishedAt":{"type":"string","nullable":true}},"required":["id","title","description","vendor","productType","tags","variants","images","videos","createdAt","updatedAt","handle"],"example":{"title":"Product Name","description":"Product description","vendor":"Vendor Name","productType":"Product Type","tags":["Tag 1","Tag 2"],"variants":[{"id":1,"title":"Variant Name","sku":"SKU123","price":"100.00","compareAtPrice":"120.00","available":true}],"images":[{"id":1,"src":"https://example.com/image.jpg","alt":"Image alt text","position":1}],"videos":[{"id":1,"src":"https://example.com/video.mp4","poster":"https://example.com/video.jpg","alt":"Video alt text","position":1}],"createdAt":"2024-01-01T00:00:00.000Z","updatedAt":"2024-01-01T00:00:00.000Z","handle":"product-name","sourceType":"shopify","publishedAt":"2024-01-01T00:00:00.000Z"}},"details":{"type":"object","nullable":true,"properties":{"research":{"type":"string","example":"## Product Description\\n\\n...\\n\\n## Key Selling Points\\n- ..."}},"required":["research"]},"researchStatus":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"completed","description":"Status of the product research workflow, if one exists."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","workspaceId","data","createdAt","updatedAt"],"description":"Product"}}},"required":["products"],"description":"GetWorkspaceProductsResponse"}}}},"400":{"description":"Invalid workspace ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspace-analyses":{"post":{"summary":"Create workspace analysis","description":"Create a new workspace analysis job. Returns immediately with a 202 Accepted status.","security":[{"APIKeyAuth":[]}],"tags":["Workspace Analyses"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/product"}},"required":["url"],"description":"CreateWorkspaceAnalysisRequest"}}}},"responses":{"202":{"description":"Analysis job created","content":{"application/json":{"schema":{"type":"object","properties":{"analysis":{"type":"object","properties":{"id":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"status":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"pending"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"results":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"required":["overview","voiceAndTone","vocabulary","brandStyles"]},"storeType":{"type":"string","enum":["shopify","product_page"]}},"required":["brand","storeType"]}},"required":["id","status","workspaceId","createdAt"],"description":"WorkspaceAnalysis"}},"required":["analysis"],"description":"CreateWorkspaceAnalysisResponse"}}}},"400":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/workspace-analyses/{id}":{"get":{"summary":"Get workspace analysis","description":"Get a workspace analysis job by ID (requires access to workspace)","security":[{"APIKeyAuth":[]}],"tags":["Workspace Analyses"],"parameters":[{"schema":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Analysis job details","content":{"application/json":{"schema":{"type":"object","properties":{"analysis":{"type":"object","properties":{"id":{"type":"string","example":"wrun_01KFZQVVR6RWZWW9R6X5CR2PP4"},"status":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"pending"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"results":{"type":"object","properties":{"brand":{"type":"object","properties":{"overview":{"type":"object","properties":{"id":{"type":"string"},"website":{"type":"string"},"name":{"type":"string","minLength":1},"industry":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"industryOther":{"type":"string"},"usp":{"type":"string","nullable":true},"competitors":{"type":"string","nullable":true},"personality":{"type":"string","nullable":true,"enum":["professional","friendly","bold","playful","visionary","warm","elegant","quirky","reliable","minimalist","high-energy","adaptive",null]},"archetype":{"type":"string","nullable":true,"enum":["Creator","Sage","Hero","Rebel","Caregiver","Ruler","Jester","Lover","Everyman","Explorer","Innocent","Magician",null]},"about":{"type":"string","nullable":true}},"required":["name"]},"voiceAndTone":{"type":"object","properties":{"voicePersona":{"type":"string","enum":["mentor","friend","expert","innovator","advocate","leader","coach","insider","guide","adaptive"]},"toneStyle":{"type":"string","enum":["confident","witty","warm","assertive","elegant","playful","inspirational","calm","bold","conversational"]},"vocabType":{"type":"string","enum":["conversational","corporate","industry-jargon","technical","evocative","plainspoken","luxury"]},"writingStyle":{"type":"string","enum":["short-punchy","balanced","long-form","varied"]},"ctaStyle":{"type":"string","enum":["direct","soft","inspirational","urgent","adaptive"]},"emotionalSignature":{"type":"string","enum":["trust","excitement","belonging","empowerment","clarity","curiosity","aspiration","safety"]}}},"vocabulary":{"type":"object","properties":{"preferredVocabulary":{"type":"string"},"bannedVocabulary":{"type":"string"},"copywritingReferences":{"type":"string"}}},"brandStyles":{"type":"object","properties":{"logos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}}},"default":[]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usage":{"type":"string"},"value":{"type":"string"}},"required":["id","name","usage","value"]},"default":[]},"fonts":{"type":"object","properties":{"heading":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]},"body":{"type":"object","properties":{"name":{"type":"string"},"custom":{"type":"boolean"}},"required":["name","custom"]}},"default":{}}}}},"required":["overview","voiceAndTone","vocabulary","brandStyles"]},"storeType":{"type":"string","enum":["shopify","product_page"]}},"required":["brand","storeType"]}},"required":["id","status","workspaceId","createdAt"],"description":"WorkspaceAnalysis"}},"required":["analysis"],"description":"GetWorkspaceAnalysisResponse"}}}},"400":{"description":"Invalid analysis ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Analysis not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/signed-url":{"post":{"summary":"Get signed URL","description":"Get a signed URL for a media storage path. Body: { path: string, expiry?: number }. Default expiry 3600 seconds.","security":[{"APIKeyAuth":[]}],"tags":["Media"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","example":"userId/productId/media/file.jpeg","description":"Storage path: user-uploads media (userId/productId/media/...) or template references (templates/references/...)"},"expiry":{"type":"integer","minimum":0,"exclusiveMinimum":true,"example":3600,"description":"Expiry in seconds, default 3600"}},"required":["path"],"description":"SignedUrlRequest"}}}},"responses":{"200":{"description":"Signed URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://example.com/file.png?token=abc123","description":"Pre-signed URL for file access"}},"required":["url"],"description":"SignedUrlResponse"}}}},"400":{"description":"Missing path","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to path","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/products":{"post":{"summary":"Insert products","description":"Insert products (Shopify or ScrapedProduct). Triggers research and media analysis workflows.","security":[{"APIKeyAuth":[]}],"tags":["Products"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"products":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"handle":{"type":"string","example":"product-handle"},"body_html":{"type":"string"},"published_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"vendor":{"type":"string"},"product_type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"images":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"options":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["id","title","handle"],"description":"ShopifyProduct"},{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"handle":{"type":"string"},"description":{"type":"string"},"price":{"type":"string"},"compareAtPrice":{"type":"string"},"vendor":{"type":"string"},"productType":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"src":{"type":"string"},"alt":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"src":{"type":"string"},"poster":{"type":"string","nullable":true},"alt":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","src","position"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"sku":{"type":"string"},"price":{"type":"string"},"compareAtPrice":{"type":"string"},"available":{"type":"boolean"}},"required":["id","title","sku","price","available"]}},"available":{"type":"boolean"}},"required":["id","title","handle","description","price","tags","images","videos","variants","available"],"description":"ScrapedProduct"}]},"minItems":1}},"required":["workspaceId","products"],"description":"CreateProductsRequest"}}}},"responses":{"200":{"description":"Products inserted","content":{"application/json":{"schema":{"type":"object","properties":{"inserted":{"type":"number","example":3},"mediaUploaded":{"type":"number","example":5},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"description":{"type":"string","example":"Product description"},"vendor":{"type":"string","example":"Vendor Name"},"productType":{"type":"string","example":"Product Type"},"tags":{"type":"array","items":{"type":"string"},"example":["Tag 1","Tag 2"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Variant Name"},"sku":{"type":"string","example":"SKU123"},"price":{"type":"string","example":"100.00"},"compareAtPrice":{"type":"string","example":"120.00"},"available":{"type":"boolean","example":true}},"required":["id","title","sku","price","available"]}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/image.jpg"},"alt":{"type":"string","nullable":true,"example":"Image alt text"},"position":{"type":"number","example":1}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/video.mp4"},"poster":{"type":"string","example":"https://example.com/video.jpg"},"alt":{"type":"string","example":"Video alt text"},"position":{"type":"number","example":1}},"required":["id","src","poster","alt","position"]}},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"handle":{"type":"string","example":"product-name"},"sourceType":{"type":"string","enum":["shopify","woocommerce","product_page"]},"publishedAt":{"type":"string","nullable":true}},"required":["id","title","description","vendor","productType","tags","variants","images","videos","createdAt","updatedAt","handle"],"example":{"title":"Product Name","description":"Product description","vendor":"Vendor Name","productType":"Product Type","tags":["Tag 1","Tag 2"],"variants":[{"id":1,"title":"Variant Name","sku":"SKU123","price":"100.00","compareAtPrice":"120.00","available":true}],"images":[{"id":1,"src":"https://example.com/image.jpg","alt":"Image alt text","position":1}],"videos":[{"id":1,"src":"https://example.com/video.mp4","poster":"https://example.com/video.jpg","alt":"Video alt text","position":1}],"createdAt":"2024-01-01T00:00:00.000Z","updatedAt":"2024-01-01T00:00:00.000Z","handle":"product-name","sourceType":"shopify","publishedAt":"2024-01-01T00:00:00.000Z"}},"details":{"type":"object","nullable":true,"properties":{"research":{"type":"string","example":"## Product Description\\n\\n...\\n\\n## Key Selling Points\\n- ..."}},"required":["research"]},"researchStatus":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"completed","description":"Status of the product research workflow, if one exists."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","workspaceId","data","createdAt","updatedAt"],"description":"Product"}}},"required":["inserted","mediaUploaded","products"],"description":"CreateProductsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/products/{id}":{"get":{"summary":"Get product","description":"Get a product by ID (requires workspace access)","security":[{"APIKeyAuth":[]}],"tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"description":{"type":"string","example":"Product description"},"vendor":{"type":"string","example":"Vendor Name"},"productType":{"type":"string","example":"Product Type"},"tags":{"type":"array","items":{"type":"string"},"example":["Tag 1","Tag 2"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Variant Name"},"sku":{"type":"string","example":"SKU123"},"price":{"type":"string","example":"100.00"},"compareAtPrice":{"type":"string","example":"120.00"},"available":{"type":"boolean","example":true}},"required":["id","title","sku","price","available"]}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/image.jpg"},"alt":{"type":"string","nullable":true,"example":"Image alt text"},"position":{"type":"number","example":1}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/video.mp4"},"poster":{"type":"string","example":"https://example.com/video.jpg"},"alt":{"type":"string","example":"Video alt text"},"position":{"type":"number","example":1}},"required":["id","src","poster","alt","position"]}},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"handle":{"type":"string","example":"product-name"},"sourceType":{"type":"string","enum":["shopify","woocommerce","product_page"]},"publishedAt":{"type":"string","nullable":true}},"required":["id","title","description","vendor","productType","tags","variants","images","videos","createdAt","updatedAt","handle"],"example":{"title":"Product Name","description":"Product description","vendor":"Vendor Name","productType":"Product Type","tags":["Tag 1","Tag 2"],"variants":[{"id":1,"title":"Variant Name","sku":"SKU123","price":"100.00","compareAtPrice":"120.00","available":true}],"images":[{"id":1,"src":"https://example.com/image.jpg","alt":"Image alt text","position":1}],"videos":[{"id":1,"src":"https://example.com/video.mp4","poster":"https://example.com/video.jpg","alt":"Video alt text","position":1}],"createdAt":"2024-01-01T00:00:00.000Z","updatedAt":"2024-01-01T00:00:00.000Z","handle":"product-name","sourceType":"shopify","publishedAt":"2024-01-01T00:00:00.000Z"}},"details":{"type":"object","nullable":true,"properties":{"research":{"type":"string","example":"## Product Description\\n\\n...\\n\\n## Key Selling Points\\n- ..."}},"required":["research"]},"researchStatus":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"completed","description":"Status of the product research workflow, if one exists."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","workspaceId","data","createdAt","updatedAt"],"description":"Product"}}}},"400":{"description":"Invalid product ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"patch":{"summary":"Update product","description":"Partially update a product. Only title, description, research, and tags are updatable.","security":[{"APIKeyAuth":[]}],"tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"research":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"description":"PatchProductRequest"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Product Name"},"description":{"type":"string","example":"Product description"},"vendor":{"type":"string","example":"Vendor Name"},"productType":{"type":"string","example":"Product Type"},"tags":{"type":"array","items":{"type":"string"},"example":["Tag 1","Tag 2"]},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"title":{"type":"string","example":"Variant Name"},"sku":{"type":"string","example":"SKU123"},"price":{"type":"string","example":"100.00"},"compareAtPrice":{"type":"string","example":"120.00"},"available":{"type":"boolean","example":true}},"required":["id","title","sku","price","available"]}},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/image.jpg"},"alt":{"type":"string","nullable":true,"example":"Image alt text"},"position":{"type":"number","example":1}},"required":["id","src","position"]}},"videos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","example":1},"src":{"type":"string","example":"https://example.com/video.mp4"},"poster":{"type":"string","example":"https://example.com/video.jpg"},"alt":{"type":"string","example":"Video alt text"},"position":{"type":"number","example":1}},"required":["id","src","poster","alt","position"]}},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"handle":{"type":"string","example":"product-name"},"sourceType":{"type":"string","enum":["shopify","woocommerce","product_page"]},"publishedAt":{"type":"string","nullable":true}},"required":["id","title","description","vendor","productType","tags","variants","images","videos","createdAt","updatedAt","handle"],"example":{"title":"Product Name","description":"Product description","vendor":"Vendor Name","productType":"Product Type","tags":["Tag 1","Tag 2"],"variants":[{"id":1,"title":"Variant Name","sku":"SKU123","price":"100.00","compareAtPrice":"120.00","available":true}],"images":[{"id":1,"src":"https://example.com/image.jpg","alt":"Image alt text","position":1}],"videos":[{"id":1,"src":"https://example.com/video.mp4","poster":"https://example.com/video.jpg","alt":"Video alt text","position":1}],"createdAt":"2024-01-01T00:00:00.000Z","updatedAt":"2024-01-01T00:00:00.000Z","handle":"product-name","sourceType":"shopify","publishedAt":"2024-01-01T00:00:00.000Z"}},"details":{"type":"object","nullable":true,"properties":{"research":{"type":"string","example":"## Product Description\\n\\n...\\n\\n## Key Selling Points\\n- ..."}},"required":["research"]},"researchStatus":{"type":"string","enum":["pending","running","completed","failed","cancelled"],"example":"completed","description":"Status of the product research workflow, if one exists."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","workspaceId","data","createdAt","updatedAt"],"description":"Product"}}}},"400":{"description":"Invalid product ID or product data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"delete":{"summary":"Delete product","description":"Delete a product and its media (requires workspace access)","security":[{"APIKeyAuth":[]}],"tags":["Products"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Product deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Invalid product ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/products/{id}/personas":{"get":{"summary":"Get product personas","description":"Get all personas for a product (requires workspace access)","security":[{"APIKeyAuth":[]}],"tags":["Personas"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of personas","content":{"application/json":{"schema":{"type":"object","properties":{"personas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Sarah, The Stylish Practicalist"},"ageRange":{"type":"string","example":"25-34"},"gender":{"type":"string","example":"female"},"data":{"type":"string","example":"Education: bachelors\\nSpending Behaviour: luxury, impulse\\n\\n## Profile\\Sarah is ..."}},"required":["id","name","ageRange","gender","data"],"description":"ProductPersonaItem"}}},"required":["personas"],"description":"GetProductPersonasResponse"}}}},"400":{"description":"Invalid product ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/personas":{"post":{"summary":"Create persona","description":"Create a persona for a product. Body: { productId, name, ageRange, gender, data }. ageRange must be {number}-{number} (e.g. \"25-34\"). gender must be \"male\" or \"female\". Requires workspace access.","security":[{"APIKeyAuth":[]}],"tags":["Personas"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":255},"ageRange":{"type":"string","pattern":"^\\d+-\\d+$","example":"25-34"},"gender":{"type":"string","enum":["male","female"]},"data":{"type":"string","minLength":1}},"required":["productId","name","ageRange","gender","data"],"description":"CreatePersonaRequest"}}}},"responses":{"201":{"description":"Persona created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"productId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Sarah, The Stylish Practicalist"},"ageRange":{"type":"string","example":"25-34"},"gender":{"type":"string","example":"female"},"data":{"type":"string","example":"Education: bachelors\\nSpending Behaviour: luxury, impulse\\n\\n## Profile\\Sarah is ..."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","productId","workspaceId","name","ageRange","gender","data","createdAt","updatedAt"],"description":"Persona"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/personas/{id}":{"patch":{"summary":"Update persona","description":"Update a persona's name, gender, ageRange, and/or data. At least one field required. Requires workspace access.","security":[{"APIKeyAuth":[]}],"tags":["Personas"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"ageRange":{"type":"string","pattern":"^\\d+-\\d+$"},"gender":{"type":"string","enum":["male","female"]},"data":{"type":"string","minLength":1}},"description":"PatchPersonaRequest"}}}},"responses":{"200":{"description":"Persona updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"productId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Sarah, The Stylish Practicalist"},"ageRange":{"type":"string","example":"25-34"},"gender":{"type":"string","example":"female"},"data":{"type":"string","example":"Education: bachelors\\nSpending Behaviour: luxury, impulse\\n\\n## Profile\\Sarah is ..."},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},"required":["id","productId","workspaceId","name","ageRange","gender","data","createdAt","updatedAt"],"description":"Persona"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Persona not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"delete":{"summary":"Delete persona","description":"Delete a persona. Requires workspace access.","security":[{"APIKeyAuth":[]}],"tags":["Personas"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Persona deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Invalid persona ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Persona not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/products/{id}/media":{"get":{"summary":"Get product media","description":"Get all media for a product. Supports limit/offset pagination. Query params: type, limit, offset.","security":[{"APIKeyAuth":[]}],"tags":["Media"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["image","video"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"number","nullable":true,"example":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"example":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Media list","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Media Name"},"type":{"type":"string","enum":["image","video","audio","document"],"example":"image"},"mimeType":{"type":"string","example":"image/png"},"fileSize":{"type":"string","example":"1024"},"storagePath":{"type":"string","example":"userId/productId/media/file.png"},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"duration":{"type":"string","nullable":true}},"required":["id","name","type","mimeType","fileSize","storagePath"],"description":"Media"}},"total":{"type":"number","example":42}},"required":["media","total"],"description":"GetProductMediaResponse"}}}},"400":{"description":"Invalid product ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/adsets/{id}":{"get":{"summary":"Get adset","description":"Get an adset by ID (requires workspace access)","security":[{"APIKeyAuth":[]}],"tags":["Adsets"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Adset details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Ad Set Name"},"status":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["generating_briefs","reviewing_briefs","generating_creatives","reviewing_creatives","rejected","errored","approved","scheduled_for_publish","published","inactive","paused","ended"]},"date":{"type":"string"}},"required":["type"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"title":{"type":"string","example":"Ad Title"},"status":{"type":"string","enum":["generating_brief","reviewing_brief","brief_rejected","generating_creative","reviewing_creative","creative_rejected","approved","errored"]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"brief":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"personaId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"data":{"type":"object","additionalProperties":{"nullable":true},"example":{}}},"required":["id","personaId","data"],"description":"Brief"}},"required":["id","title","status"],"description":"Ad"}}},"required":["id","name","ads"],"description":"AdSet"}}}},"400":{"description":"Invalid adset ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Adset not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"delete":{"summary":"Delete adset","description":"Delete an adset (requires workspace access)","security":[{"APIKeyAuth":[]}],"tags":["Adsets"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Adset deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Invalid adset ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Adset not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/export-adset":{"post":{"summary":"Export adset ads","description":"Start an export workflow for an adset. Body: { adsetId, adIds?: string[] }. Returns 202 with workflowRunId. Poll GET /v1/export-adset/{id} for status. By default exports all approved ads. API key only.","security":[{"APIKeyAuth":[]}],"tags":["Export"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"adsetId":{"type":"string","format":"uuid"},"adIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional subset of ad IDs to export. Defaults to all approved ads.","example":["123e4567-e89b-12d3-a456-426614174000"]}},"required":["adsetId"]}}}},"responses":{"202":{"description":"Export workflow started","content":{"application/json":{"schema":{"type":"object","properties":{"workflowRunId":{"type":"string","description":"Use this ID to poll GET /v1/export-adset/{id} for status","example":"wfr_abc123"}},"required":["workflowRunId"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"AdSet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/export-adset/{id}":{"get":{"summary":"Get export status","description":"Poll export workflow progress. id = workflowRunId from POST response. Returns processing with progress, complete with urls, or error. API key only.","security":[{"APIKeyAuth":[]}],"tags":["Export"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Export status","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["processing"]},"progress":{"type":"number","minimum":0,"maximum":100}},"required":["status","progress"]},{"type":"object","properties":{"status":{"type":"string","enum":["complete"]},"urls":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"description":"Export URLs keyed by ad ID, each containing aspect ratio to URL mappings","example":{"ad-uuid-1":{"9:16":"https://example.com/video-9x16.mp4","1:1":"https://example.com/video-1x1.mp4","16:9":"https://example.com/video-16x9.mp4"}}}},"required":["status","urls"]},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string"}},"required":["status","error"]}]}}}},"400":{"description":"Invalid workflow run ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Workflow run not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/media/{id}":{"get":{"summary":"Get media","description":"Get media by ID (requires access)","security":[{"APIKeyAuth":[]}],"tags":["Media"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Media details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Media Name"},"type":{"type":"string","enum":["image","video","audio","document"],"example":"image"},"mimeType":{"type":"string","example":"image/png"},"fileSize":{"type":"string","example":"1024"},"storagePath":{"type":"string","example":"userId/productId/media/file.png"},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"duration":{"type":"string","nullable":true}},"required":["id","name","type","mimeType","fileSize","storagePath"],"description":"Media"}}}},"400":{"description":"Invalid media ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Media not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}},"delete":{"summary":"Delete media","description":"Delete media (requires access)","security":[{"APIKeyAuth":[]}],"tags":["Media"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Media deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"example":true}},"required":["success"],"description":"SuccessResponse"}}}},"400":{"description":"Invalid media ID","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Media not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/adsets":{"post":{"summary":"Create adset","description":"Create a new adset with zero or more ads and briefs. Each ad must include title, personaId, and a full brief payload. Use an empty ads array to create an adset without ads, then add ads via POST /v1/ads.\n\nImportant: brief is a discriminated object. Set brief.type first.\n- brief.type=\"static\": send concept, aspectRatio, textElements, hasLogo, mediaIds, and metaAdCopy.\n- brief.type=\"video\": send concept, scenes, mediaIds, metaAdCopy, and optional avatar/voice/music objects.\n\nWhen templateId is set, first inspect GET /v1/templates. For static templates, copy metadata.textElements into brief.textElements and metadata.visualElements.hasLogo into brief.hasLogo. For video templates, copy metadata.scenesStructure into brief.scenes. templateId does not infer omitted fields automatically.","security":[{"APIKeyAuth":[]}],"tags":["Adsets"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"productId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","minLength":1,"example":"My Ad Set"},"ads":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"example":"Product Video Ad 1"},"personaId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"templateId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"Template ID from GET /v1/templates. When set, first inspect the template metadata, then send a complete brief payload that matches the selected brief.type."},"brief":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Full brief payload. Step 1: set brief.type to \"static\" or \"video\". Step 2: include all required fields for that type. If templateId is set, copy static text slot metadata from metadata.textElements or copy video scene metadata from metadata.scenesStructure."}},"required":["title","personaId","brief"]}}},"required":["workspaceId","productId","name","ads"],"description":"CreateAdsetRequest","example":{"workspaceId":"28a1908f-6705-4b8c-97de-82daab2048a6","productId":"d7bfd420-bb05-4638-adc8-85c27d237281","name":"Capra Negra Full Mix Adset","ads":[{"title":"Ad 1 - Static Product Spotlight","personaId":"bbdd23a8-2afd-437d-9cf0-93e8bfb809a4","templateId":"8f844022-1306-48ba-8418-59e5244610fc","brief":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"title":"Ad 2 - UGC Video","personaId":"6425fbd4-ed04-4308-90c1-31e64054c563","templateId":"fe21522e-6d58-4ae3-bc8c-1537aff328c8","brief":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}]}}}}},"responses":{"200":{"description":"Adset created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"]},"productId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["generating_brief","reviewing_brief","brief_rejected","generating_creative","reviewing_creative","creative_rejected","approved","errored"]},"schema":{"nullable":true},"brief":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"data":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Discriminated brief payload. Set brief.type first, then follow the matching schema. templateId does not infer omitted fields."},"personaId":{"type":"string","format":"uuid"},"templateId":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","data","personaId","templateId"]}},"required":["id","title","status","brief"]}}},"required":["id","name","status","productId","workspaceId","ads"],"description":"CreateAdsetResponse"}}}},"400":{"description":"Invalid request data or persona does not belong to product","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Product or persona not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/ads":{"post":{"summary":"Create ad","description":"Create a single ad in an existing adset. Body: { adSetId, title, personaId, templateId?, brief }. Persona must belong to the adset's product. Brief is a discriminated object—set brief.type to \"static\" or \"video\" and include all required fields for that type.","security":[{"APIKeyAuth":[]}],"tags":["Ads"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"adSetId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"title":{"type":"string","minLength":1,"example":"Product Video Ad 1"},"personaId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"templateId":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000","description":"Template ID from GET /v1/templates. When set, first inspect the template metadata, then send a complete brief payload that matches the selected brief.type."},"brief":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Full brief payload. Step 1: set brief.type to \"static\" or \"video\". Step 2: include all required fields for that type. If templateId is set, copy static text slot metadata from metadata.textElements or copy video scene metadata from metadata.scenesStructure."}},"required":["adSetId","title","personaId","brief"],"description":"CreateAdRequest","example":{"adSetId":"28a1908f-6705-4b8c-97de-82daab2048a6","title":"Ad 1 - Static Product Spotlight","personaId":"bbdd23a8-2afd-437d-9cf0-93e8bfb809a4","templateId":"8f844022-1306-48ba-8418-59e5244610fc","brief":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}}}}}},"responses":{"200":{"description":"Ad created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["generating_brief","reviewing_brief","brief_rejected","generating_creative","reviewing_creative","creative_rejected","approved","errored"]},"schema":{"nullable":true},"brief":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"data":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Discriminated brief payload. Set brief.type first, then follow the matching schema. templateId does not infer omitted fields."},"personaId":{"type":"string","format":"uuid"},"templateId":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","data","personaId","templateId"]}},"required":["id","title","status","brief"],"description":"CreateAdResponse"}}}},"400":{"description":"Invalid request or persona does not belong to product","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Ad set or persona not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/ads/{id}":{"patch":{"summary":"Update ad","description":"Update an ad's title and/or brief data. Note: brief can only be edited when ad status is \"reviewing_brief\".","security":[{"APIKeyAuth":[]}],"tags":["Ads"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1},"briefData":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Discriminated brief payload. Set brief.type first, then follow the matching schema. templateId does not infer omitted fields."}},"description":"PatchAdRequest"}}}},"responses":{"200":{"description":"Ad updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ad":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"adSetId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["generating_brief","reviewing_brief","brief_rejected","generating_creative","reviewing_creative","creative_rejected","approved","errored"]},"schema":{"nullable":true},"metadata":{"nullable":true},"brief":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"data":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["static"],"description":"Discriminator for a static/image ad brief. Always set brief.type to \"static\" for image templates.","example":"static"},"concept":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes"],"description":"Static ad concept.","example":"product_spotlight"},"aspectRatio":{"type":"string","enum":["1:1","9:16","4:5"],"description":"Output aspect ratio. Use the ratio expected by the template.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text element type copied from the template metadata.textElements[].type.","example":"headline"},"originalContent":{"type":"string","description":"Original text from the template metadata.textElements[].content.","example":"NEW ACCESSORY"},"productContent":{"type":"string","description":"Your product-specific replacement for the original template text.","example":"CAPRA NEGRA OUTDOOR KNIFE"},"position":{"type":"string","description":"Text position copied from the template metadata.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Priority copied from the template metadata.textElements[].importance.","example":"high"}},"required":["type","originalContent","productContent","position","importance"],"description":"One text slot for a static template. When templateId is set, copy type, originalContent, position, and importance from template metadata, then fill productContent."},"description":"Static text slots. When templateId is set, build this from template metadata.textElements."},"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy from template metadata.visualElements.hasLogo when using a template.","example":false},"replaceLogo":{"type":"boolean","default":true,"description":"When true and hasLogo is true, the template logo slot will be replaced with the brand logo. Defaults to true.","example":true},"customInstructions":{"type":"string","default":"","description":"Optional additional creative instructions for the generation step.","example":""},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing product media IDs to use in the creative. Pass an empty array when no existing media is required.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."}},"required":["type","concept","aspectRatio","textElements","hasLogo","mediaIds","metaAdCopy"],"description":"Full static brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"static","concept":"product_spotlight","aspectRatio":"9:16","textElements":[{"type":"headline","originalContent":"NEW ACCESSORY","productContent":"CAPRA NEGRA OUTDOOR KNIFE","position":"top-center","importance":"high"}],"hasLogo":false,"mediaIds":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"],"metaAdCopy":{"primaryText":"Built for trails, camping, and everyday carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel blade with paracord handle.","cta":"SHOP_NOW"}}},{"type":"object","properties":{"type":{"type":"string","enum":["video"],"description":"Discriminator for a video ad brief. Always set brief.type to \"video\" for video templates.","example":"video"},"concept":{"type":"string","enum":["ugc","product_demo","explainer","vsl"],"description":"Video ad concept.","example":"ugc"},"scenes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label. When templateId is set, copy from template metadata.scenesStructure[].label.","example":"Hook"},"mediaSource":{"type":"string","enum":["existing","generation"],"description":"How scene media is produced: \"existing\" uses provided mediaIds, \"generation\" creates new media.","example":"generation"},"useMediaForGeneration":{"type":"boolean","description":"Optional hint to use provided media as generation reference input.","example":false},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product"],"description":"Concrete scene type. When templateId is set, copy from template metadata.scenesStructure[].sceneType.","example":"avatar-with-product"},"script":{"type":"string","description":"Voiceover or spoken script for the scene.","example":"This is the compact knife I keep with me on every hike."},"description":{"type":"string","description":"Visual production instructions for the scene. Be explicit about framing, setting, lighting, and action.","example":"Vertical 9:16 selfie shot in a pine forest. A man in hiking gear holds the knife close to camera in soft natural light."},"seconds":{"anyOf":[{"type":"number","enum":[4]},{"type":"number","enum":[6]},{"type":"number","enum":[8]}],"description":"Scene duration. Only 4, 6, or 8 seconds are allowed.","example":4}},"required":["label","mediaSource","sceneType","script","description","seconds"],"description":"One scene in a video brief. When templateId is set, copy label and sceneType from template metadata.scenesStructure, then fill the creative details."},"description":"Video scenes. When templateId is set, build this from template metadata.scenesStructure."},"mediaIds":{"type":"array","items":{"type":"string"},"description":"Existing media IDs available for scenes that use mediaSource=\"existing\". Pass an empty array if all scenes are generated.","example":["2f67e5b0-b395-4f1f-a14e-11e5f3edfd0f"]},"metaAdCopy":{"type":"object","properties":{"primaryText":{"type":"string","description":"Primary ad copy shown in the feed.","example":"Meet the compact outdoor knife built for every trail."},"headline":{"type":"string","description":"Headline shown in the ad card.","example":"Capra Negra Outdoor Knife"},"description":{"type":"string","description":"Optional supporting copy shown below the headline.","example":"D2 steel blade, paracord handle, kydex sheath included."},"cta":{"type":"string","enum":["SHOP_NOW","LEARN_MORE","SIGN_UP","DOWNLOAD","BOOK_TRAVEL","CONTACT_US","GET_OFFER","GET_QUOTE","SUBSCRIBE","WATCH_MORE","ORDER_NOW","BUY_NOW","VIEW_PRODUCT","BUY"],"description":"Meta CTA button value.","example":"SHOP_NOW"}},"required":["primaryText","headline","description","cta"],"description":"Meta ad copy that will be attached to the generated creative."},"avatar":{"type":"object","properties":{"id":{"type":"string","description":"Avatar ID from GET /v1/avatars.","example":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"}},"required":["id"],"description":"Optional avatar selection. Use object form { id }, not avatarId."},"voice":{"type":"object","properties":{"id":{"type":"string","description":"Voice ID from GET /v1/voices.","example":"Q1khAM9K4Mi6p5TK0ueC"}},"required":["id"],"description":"Optional voice selection. Use object form { id }, not voiceId."},"music":{"type":"object","properties":{"id":{"type":"string","description":"Music ID from GET /v1/music.","example":"commercial-upbeat-energetic-rock-354637"},"enabled":{"type":"boolean","description":"Whether background music should be used.","example":true}},"required":["id","enabled"],"description":"Optional music selection. Use object form { id, enabled }, not musicId."}},"required":["type","concept","scenes","mediaIds","metaAdCopy"],"description":"Full video brief payload. Required fields are not inferred from templateId; send the complete brief.","example":{"type":"video","concept":"ugc","scenes":[{"label":"Hook","mediaSource":"generation","sceneType":"avatar-with-product","script":"I tested a lot of knives. This is the one I keep reaching for.","description":"Vertical 9:16 selfie shot in a forest. A man in hiking clothes holds the knife close to camera with a confident smile.","seconds":4}],"mediaIds":[],"metaAdCopy":{"primaryText":"A compact fixed-blade knife built for outdoor carry.","headline":"Capra Negra Outdoor Knife","description":"D2 steel. Paracord handle. Kydex sheath included.","cta":"SHOP_NOW"},"avatar":{"id":"f6d6d4e5-33ae-407b-a758-7cd24f19cce6"},"voice":{"id":"Q1khAM9K4Mi6p5TK0ueC"},"music":{"id":"commercial-upbeat-energetic-rock-354637","enabled":true}}}],"description":"Discriminated brief payload. Set brief.type first, then follow the matching schema. templateId does not infer omitted fields."},"personaId":{"type":"string","format":"uuid"},"templateId":{"type":"string","nullable":true,"format":"uuid"}},"required":["id","data","personaId","templateId"]}},"required":["id","title","adSetId","status","brief"],"description":"Updated ad with brief nested inside"}},"required":["ad"],"description":"PatchAdResponse"}}}},"400":{"description":"Invalid request or brief can only be edited when status is reviewing_brief","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"404":{"description":"Ad not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/avatars":{"get":{"summary":"List avatars","description":"List all published avatars with optional filters for gender, age, and setting. Supports limit/offset pagination. Returns avatars with signed image and video URLs.","security":[{"APIKeyAuth":[]}],"tags":["Avatars"],"parameters":[{"schema":{"type":"string","enum":["male","female"]},"required":false,"name":"gender","in":"query"},{"schema":{"type":"string","enum":["young_adult","adult","senior"]},"required":false,"name":"age","in":"query"},{"schema":{"type":"string","enum":["studio","office","living_room","bedroom","kitchen","bathroom","home","car","gym","coffee_shop","nature","outside","street","streaming","formal"]},"required":false,"name":"setting","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of avatars","content":{"application/json":{"schema":{"type":"object","properties":{"avatars":{"type":"array","items":{"type":"object","properties":{"avatar":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"gender":{"type":"string","enum":["male","female"]},"age":{"type":"number"},"race":{"type":"string","enum":["caucasian","asian","african_american","hispanic","middle_eastern","south_asian","mixed"]},"setting":{"type":"string","nullable":true,"enum":["studio","office","living_room","bedroom","kitchen","bathroom","home","car","gym","coffee_shop","nature","outside","street","streaming","formal",null]},"imageStoragePath":{"type":"string","nullable":true},"videoStoragePath":{"type":"string","nullable":true},"status":{"type":"string","enum":["processing","review","published","errored"]},"metadata":{"nullable":true},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","gender","age","race","setting","imageStoragePath","videoStoragePath","status","createdAt","updatedAt"]},"imageUrl":{"type":"string","nullable":true},"videoUrl":{"type":"string","nullable":true}},"required":["avatar","imageUrl","videoUrl"]}},"total":{"type":"number"}},"required":["avatars","total"],"description":"GetAvatarsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/templates":{"get":{"summary":"List templates","description":"List published templates with optional filters for type, industry, concept, and workspaceId. Supports limit/offset pagination.\n\nEach template is typed:\n- type=\"staticAd\": metadata describes aspectRatio, textElements, and visualElements used to build brief.type=\"static\".\n- type=\"videoAd\": metadata describes sceneCount and scenesStructure used to build brief.type=\"video\".","security":[{"APIKeyAuth":[]}],"tags":["Templates"],"parameters":[{"schema":{"type":"string","enum":["videoAd","staticAd"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]},"required":false,"name":"industry","in":"query"},{"schema":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes","ugc","product_demo","explainer","vsl"]},"required":false,"name":"concept","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"workspaceId","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of templates","content":{"application/json":{"schema":{"type":"object","properties":{"templates":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"concepts":{"type":"array","items":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes","ugc","product_demo","explainer","vsl"]}},"industries":{"type":"array","items":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]}},"storagePath":{"type":"string","nullable":true},"workspaceId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["staticAd"],"description":"Static/image template type.","example":"staticAd"},"metadata":{"type":"object","properties":{"aspectRatio":{"type":"string","enum":["1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9"],"description":"Static template aspect ratio.","example":"9:16"},"textElements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Text slot type to copy into brief.textElements[].type.","example":"headline"},"content":{"type":"string","description":"Original template copy to copy into brief.textElements[].originalContent.","example":"NEW ACCESSORY"},"position":{"type":"string","description":"Text slot position to copy into brief.textElements[].position.","example":"top-center"},"importance":{"type":"string","description":"Text slot priority to copy into brief.textElements[].importance.","example":"high"}},"required":["type","content","position","importance"]},"description":"Static text slots. Copy these into the brief and replace only the productContent values."},"visualElements":{"type":"object","properties":{"hasLogo":{"type":"boolean","description":"Whether the template includes a logo. Copy into brief.hasLogo.","example":false},"productImageCount":{"type":"number","description":"Recommended number of product images for the template.","example":1},"backgroundStyle":{"type":"string","description":"Background style guidance for the template.","example":"clean studio gradient"},"layout":{"type":"string","description":"Layout guidance for the template.","example":"single product center with stacked text"}},"required":["hasLogo","productImageCount","backgroundStyle","layout"]},"additionalInfo":{"type":"string","description":"Additional notes for using the template.","example":"Keep headline short and bold."}},"required":["aspectRatio","textElements","visualElements","additionalInfo"],"description":"Metadata for a static template. Use it to build brief.type=\"static\"."}},"required":["id","name","description","concepts","industries","storagePath","workspaceId","createdAt","updatedAt","type","metadata"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"concepts":{"type":"array","items":{"type":"string","enum":["announcements_updates","features_and_benefits","before_and_after","product_spotlight","comparison","social_proof","problem_solution","case_study_statistics","collage","screenshot","memes","ugc","product_demo","explainer","vsl"]}},"industries":{"type":"array","items":{"type":"string","enum":["fashion_apparel","beauty_personal_care","health_fitness","food_beverage","home_lifestyle","parenting_baby","pets","travel_experiences","consumer_tech_electronics","ecommerce_dtc","education_elearning","marketing_advertising","b2b_saas","finance_fintech","healthcare_medical","real_estate_property","other"]}},"storagePath":{"type":"string","nullable":true},"workspaceId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["videoAd"],"description":"Video template type.","example":"videoAd"},"metadata":{"type":"object","properties":{"sceneCount":{"type":"number","description":"Expected number of scenes in the video brief.","example":6},"scenesStructure":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Scene label to copy into brief.scenes[].label.","example":"Hook"},"instructions":{"type":"string","description":"Creative guidance for the scene that can be used when writing script and description.","example":"Open with a strong first-person reaction that creates curiosity."},"sceneType":{"type":"string","enum":["image","video","avatar-only","avatar-with-product","image-or-video"],"description":"Template scene type to map into a concrete brief.scenes[].sceneType.","example":"avatar-with-product"}},"required":["label","instructions","sceneType"]},"description":"Video scene blueprint. Copy label and sceneType into the brief, then write script, description, mediaSource, and seconds."},"instructions":{"type":"string","description":"General video-level guidance for the whole template.","example":"Keep pacing fast and every scene under 8 seconds."}},"required":["sceneCount","scenesStructure"],"description":"Metadata for a video template. Use it to build brief.type=\"video\"."}},"required":["id","name","description","concepts","industries","storagePath","workspaceId","createdAt","updatedAt","type","metadata"]}],"description":"Published template. Inspect type and metadata before constructing an ad brief."}},"total":{"type":"number"}},"required":["templates","total"],"description":"GetTemplatesResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/voices":{"get":{"summary":"List voices","description":"List voices filtered by workspace language. Returns voices matching the workspace's language with preview URLs. Requires workspaceId query parameter.","security":[{"APIKeyAuth":[]}],"tags":["Voices"],"parameters":[{"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"workspaceId","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"minVoices","in":"query"}],"responses":{"200":{"description":"List of voices","content":{"application/json":{"schema":{"type":"object","properties":{"voices":{"type":"array","items":{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"previewUrl":{"type":"string"},"labels":{"type":"object","properties":{"gender":{"type":"string"},"age":{"type":"string"},"accent":{"type":"string"},"descriptive":{"type":"string"},"use case":{"type":"string"}}},"verifiedLanguages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"modelId":{"type":"string"},"accent":{"type":"string"},"locale":{"type":"string"},"previewUrl":{"type":"string"}},"required":["language"]}}},"required":["voiceId","name"]}},"workspace_language":{"type":"object","properties":{"isoCode":{"type":"string"},"name":{"type":"string"}},"required":["isoCode","name"]},"total":{"type":"number"}},"required":["voices","workspace_language","total"],"description":"GetVoicesResponse"}}}},"400":{"description":"Invalid workspace ID or missing workspaceId","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"403":{"description":"Forbidden - no access to workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}},"/v1/music":{"get":{"summary":"List music tracks","description":"List all available music tracks for briefs. Returns pre-defined music tracks from Pixabay with playback URLs.","security":[{"APIKeyAuth":[]}],"tags":["Music"],"responses":{"200":{"description":"List of music tracks","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"title":{"type":"string"},"volume":{"type":"number"}},"required":["id","url","title"]}},"total":{"type":"number"}},"required":["tracks","total"],"description":"GetMusicResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Error message"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"ads.0.brief.textElements.0.productContent"},"message":{"type":"string","example":"Required"},"code":{"type":"string","example":"invalid_type"}},"required":["path","message"],"description":"ValidationIssue"},"description":"Flat list of validation issues; present when error is due to schema validation","example":[{"path":"ads.0.brief.type","message":"Invalid enum value. Expected 'static' | 'video'","code":"invalid_enum_value"}]},"details":{"nullable":true,"description":"Verbose hierarchical error tree (from z.treeifyError); structure: { errors?: string[], properties?: Record, items?: Array }. Traverse via details.properties?.fieldName or details.items?.[index]"}},"required":["error"],"description":"Error"}}}}}}}},"tags":[{"name":"Workspaces","description":"Workspace management and configuration"},{"name":"Brand","description":"Brand identity and logos"},{"name":"Workspace Analyses","description":"Store URL analysis and workspace creation"},{"name":"Scrape Products","description":"Product scraping from URLs"},{"name":"Products","description":"Product catalog and management"},{"name":"Personas","description":"Buyer personas for products"},{"name":"Avatars","description":"Published avatars for video briefs"},{"name":"Templates","description":"Ad templates for static and video ads"},{"name":"Voices","description":"Voice options for workspace language"},{"name":"Music","description":"Music tracks for briefs"},{"name":"Generate Adsets","description":"Ad set and creative generation"},{"name":"Adsets","description":"Ad set management"},{"name":"Ads","description":"Individual ad management"},{"name":"Export","description":"Ad set export"},{"name":"Media","description":"Media assets"}]}