{ "openapi": "3.0.3", "info": { "title": "Wevion API", "description": "Public REST API catalog for generated clients and automation. Backoffice-only operations are intentionally excluded.", "version": "1.0.0", "contact": { "name": "Wevion Support", "email": "support@wevion.ai", "url": "https://wevion.ai" }, "license": { "name": "Proprietary", "url": "https://wevion.ai/legal/terms" } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code (mirrors the response status)." }, "error": { "type": "string", "description": "Short human-readable error class (e.g. \"Bad Request\")." }, "message": { "type": "string", "description": "Human-readable description of what went wrong." }, "code": { "type": "string", "description": "Optional stable machine-readable identifier (snake_case)." }, "request_id": { "type": "string", "description": "Fastify request id, propagated for support correlation." }, "details": { "type": "object", "additionalProperties": true, "description": "Optional structured payload (e.g. field-level validation errors)." } }, "additionalProperties": false }, "PaginationMeta": { "type": "object", "required": [ "page", "pageSize", "total" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" } }, "additionalProperties": true } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key created via `/api/v1/api-keys`. Send as `x-api-key: ` header. Permissions are scoped per key at creation time." }, "stripeSignature": { "type": "apiKey", "in": "header", "name": "stripe-signature", "description": "Stripe webhook signature. Verified server-side via Stripe SDK against STRIPE_WEBHOOK_SECRET. See https://stripe.com/docs/webhooks/signatures" }, "hmacSha256": { "type": "apiKey", "in": "header", "name": "x-hub-signature-256", "description": "HMAC-SHA256 signature of the raw request body, formatted as `sha256=`. Verified server-side against the provider-specific webhook secret." }, "featurebaseSignature": { "type": "apiKey", "in": "header", "name": "x-webhook-signature", "description": "Featurebase webhook signature. HMAC-SHA256 (hex) over `.`, verified server-side against FEATUREBASE_WEBHOOK_SECRET with a 5-minute timestamp tolerance (anti-replay). REQUIRES the companion `x-webhook-timestamp` header (unix seconds) alongside this `x-webhook-signature` header." }, "cioReportingSignature": { "type": "apiKey", "in": "header", "name": "x-cio-signature", "description": "Customer.io reporting webhook signature. HMAC-SHA256 (hex) over `v0::`, verified server-side against CIO_REPORTING_WEBHOOK_SECRET. See https://docs.customer.io/integrations/data-out/connections/webhooks/" }, "telegramSecretToken": { "type": "apiKey", "in": "header", "name": "x-telegram-bot-api-secret-token", "description": "Secret token configured via Telegram Bot API `setWebhook`. Compared in constant-time against TELEGRAM_WEBHOOK_SECRET / BETA_FEEDBACK_WEBHOOK_SECRET. See https://core.telegram.org/bots/api#setwebhook" } } }, "paths": { "/ads-status/delete-campaigns": { "post": { "operationId": "postAdsStatusDeleteCampaigns", "summary": "Delete campaigns by account from ads_status sheet", "tags": [ "ads" ], "description": "Receives a list of account rows and deletes all campaigns associated with each account in Meta.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "sheet_id", "rows" ], "properties": { "sheet_id": { "description": "Session or batch identifier.", "type": "string" }, "rows": { "description": "Array of account rows to process.", "minItems": 1, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "sheet_row_number", "account_id", "bm_id" ], "properties": { "sheet_row_number": { "description": "Row number for tracking purposes.", "type": "number" }, "account_id": { "description": "Meta Ad Account ID (column identifier).", "type": "string" }, "bm_id": { "description": "Business Manager ID (column identifier).", "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "summary" ], "properties": { "message": { "type": "string" }, "summary": { "type": "object", "required": [ "total_tasks", "skipped_count", "accounts_processed" ], "properties": { "total_tasks": { "type": "number" }, "skipped_count": { "type": "number" }, "accounts_processed": { "type": "number" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/ads-status": { "post": { "operationId": "postAdsStatus", "summary": "Execute ads checker", "tags": [ "ads" ], "description": "Receives a sheet id, retrieve all associated accounts and then update ads status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "sheet_id" ], "properties": { "sheet_id": { "description": "The ID of the sheet containing ad data.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/ads/actions": { "put": { "operationId": "putAdsActions", "summary": "Process ad toggle actions", "tags": [ "ads" ], "description": "Receives a list of ad toggle actions and processes them asynchronously via SQS workers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "sheet_id", "rows" ], "properties": { "sheet_id": { "description": "Session or batch identifier.", "type": "string" }, "rows": { "description": "Array of ad actions to process.", "minItems": 1, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "sheet_row_number", "ad_id", "account_id", "bm_id" ], "properties": { "sheet_row_number": { "description": "Row number for tracking purposes.", "type": "number" }, "ad_id": { "description": "Meta WevionAd ID to toggle.", "type": "string" }, "account_id": { "description": "Meta WevionAd Account ID associated with the ad.", "type": "string" }, "bm_id": { "description": "Business Manager ID.", "type": "string" }, "toggle_action": { "description": "Whether to toggle the ad. Defaults to false if not provided.", "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "delete_action": { "description": "Delete (archive) the ad on Meta.", "type": "boolean" } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "207": { "description": "Multi-status - partial success", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "errors" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "ad_id", "action", "error" ], "properties": { "ad_id": { "type": "string" }, "action": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/adsets/actions": { "put": { "operationId": "putAdsetsActions", "summary": "Process adset actions (edit bid and/or toggle", "tags": [ "ads" ], "description": "Receives a batch of adset actions and processes them asynchronously via SQS.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "sheet_id", "rows" ], "properties": { "sheet_id": { "description": "The ID of the Google Sheet.", "type": "string" }, "rows": { "description": "Array of adset actions to process.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "adset_id", "bm_id", "account_id", "sheet_row_number" ], "properties": { "adset_id": { "description": "The ID of the Meta Ad Set.", "type": "string" }, "bm_id": { "description": "The business manager ID.", "type": "string" }, "account_id": { "description": "The ad account ID.", "type": "string" }, "new_bid_amount": { "description": "New bid amount in cents (minimum currency units). Passed directly to Meta API.", "type": "number" }, "new_daily_budget": { "description": "New daily budget in cents (minimum currency units). Passed directly to Meta API.", "type": "number" }, "toggle_action": { "description": "Whether to turn off the adset.", "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "delete_action": { "description": "Delete (archive) the adset on Meta.", "type": "boolean" }, "sheet_row_number": { "description": "Real row number in Google Sheet (1-based).", "type": "number" } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "207": { "description": "Multi-status - partial success", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "errors" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "adset_id", "action", "error" ], "properties": { "adset_id": { "type": "string" }, "action": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/account-health": { "get": { "operationId": "getApiV1AccountHealth", "summary": "List ad account health snapshots", "tags": [ "account-health" ], "description": "Returns the latest health score snapshot for each accessible ad account.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "accounts", "last_updated" ], "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "platform", "ad_account_id", "account_name", "owner_email", "score", "level", "breakdown", "delta_1d", "delta_7d", "snapshot_date", "details" ], "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] } ] }, "ad_account_id": { "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "integer" }, "level": { "anyOf": [ { "type": "string", "enum": [ "healthy" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "critical" ] } ] }, "breakdown": { "type": "object", "required": [ "spend_efficiency", "performance_trend", "operational_errors", "creative_fatigue" ], "properties": { "spend_efficiency": { "type": "number" }, "performance_trend": { "type": "number" }, "operational_errors": { "type": "number" }, "creative_fatigue": { "type": "number" } } }, "delta_1d": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "delta_7d": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "snapshot_date": { "format": "date", "type": "string" }, "details": { "additionalProperties": false, "type": "object", "properties": { "account_active": { "type": "boolean" }, "account_status": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "conversions_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cpc_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr_decay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frequency_avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rejected_campaigns": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_total": { "type": "number" }, "target_roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } }, "last_updated": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } } } } }, "/api/v1/account-health/{platform}/{account_id}": { "get": { "operationId": "getApiV1AccountHealthByPlatformByAccountId", "summary": "Get ad account health snapshot", "tags": [ "account-health" ], "description": "Returns the latest health score snapshot for one platform account.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] } ] }, "in": "path", "name": "platform", "required": true }, { "schema": { "minLength": 1, "maxLength": 50, "type": "string" }, "in": "path", "name": "account_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "ad_account_id", "account_name", "owner_email", "score", "level", "breakdown", "delta_1d", "delta_7d", "snapshot_date", "details" ], "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] } ] }, "ad_account_id": { "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "integer" }, "level": { "anyOf": [ { "type": "string", "enum": [ "healthy" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "critical" ] } ] }, "breakdown": { "type": "object", "required": [ "spend_efficiency", "performance_trend", "operational_errors", "creative_fatigue" ], "properties": { "spend_efficiency": { "type": "number" }, "performance_trend": { "type": "number" }, "operational_errors": { "type": "number" }, "creative_fatigue": { "type": "number" } } }, "delta_1d": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "delta_7d": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "snapshot_date": { "format": "date", "type": "string" }, "details": { "additionalProperties": false, "type": "object", "properties": { "account_active": { "type": "boolean" }, "account_status": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "conversions_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cpc_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr_decay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr_delta": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frequency_avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rejected_campaigns": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_total": { "type": "number" }, "target_roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } } } } }, "/api/v1/account-health/{platform}/{account_id}/history": { "get": { "operationId": "getApiV1AccountHealthByPlatformByAccountIdHistory", "summary": "Get ad account health history", "tags": [ "account-health" ], "description": "Returns historical component scores for one platform account.", "parameters": [ { "schema": { "minimum": 1, "maximum": 365, "type": "integer" }, "in": "query", "name": "days", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] } ] }, "in": "path", "name": "platform", "required": true }, { "schema": { "minLength": 1, "maxLength": 50, "type": "string" }, "in": "path", "name": "account_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "platform", "ad_account_id", "items" ], "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] } ] }, "ad_account_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "snapshot_date", "total_score", "spend_efficiency", "performance_trend", "operational_errors", "creative_fatigue" ], "properties": { "snapshot_date": { "format": "date", "type": "string" }, "total_score": { "type": "integer" }, "spend_efficiency": { "type": "integer" }, "performance_trend": { "type": "integer" }, "operational_errors": { "type": "integer" }, "creative_fatigue": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } } } } }, "/api/v1/account-health/config": { "get": { "operationId": "getApiV1AccountHealthConfig", "summary": "Get account health configuration", "tags": [ "account-health" ], "description": "Returns the authenticated user account health scoring and alert configuration.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "alert_threshold_drop", "alert_threshold_min", "target_roas", "alert_cooldown_hours" ], "properties": { "alert_threshold_drop": { "minimum": 1, "maximum": 100, "type": "integer" }, "alert_threshold_min": { "minimum": 0, "maximum": 100, "type": "integer" }, "target_roas": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] }, "alert_cooldown_hours": { "minimum": 1, "maximum": 168, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } } } }, "put": { "operationId": "putApiV1AccountHealthConfig", "summary": "Update account health configuration", "tags": [ "account-health" ], "description": "Updates account health scoring and alert thresholds for the authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alert_threshold_drop": { "minimum": 1, "maximum": 100, "type": "integer" }, "alert_threshold_min": { "minimum": 0, "maximum": 100, "type": "integer" }, "target_roas": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] }, "alert_cooldown_hours": { "minimum": 1, "maximum": 168, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "alert_threshold_drop", "alert_threshold_min", "target_roas", "alert_cooldown_hours" ], "properties": { "alert_threshold_drop": { "minimum": 1, "maximum": 100, "type": "integer" }, "alert_threshold_min": { "minimum": 0, "maximum": 100, "type": "integer" }, "target_roas": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ] }, "alert_cooldown_hours": { "minimum": 1, "maximum": 168, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "error_code": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/{accountId}/conversion-events": { "get": { "operationId": "getApiV1AdAccountsByAccountIdConversionEvents", "summary": "List available pixel conversion events for an ad account", "tags": [ "ad-accounts" ], "description": "Discovers pixel conversion events from the last 30 days of ad insights data for the specified ad account.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "action_type", "count" ], "properties": { "action_type": { "type": "string" }, "count": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/{accountId}/conversion-settings": { "get": { "operationId": "getApiV1AdAccountsByAccountIdConversionSettings", "summary": "Get current conversion settings for an ad account", "tags": [ "ad-accounts" ], "description": "Returns the default optimization event and optional default pixel id stored for the requested Meta ad account, scoped to the caller team.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "default_conversion_event", "default_conversion_pixel_id" ], "properties": { "default_conversion_event": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_conversion_pixel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "put": { "operationId": "putApiV1AdAccountsByAccountIdConversionSettings", "summary": "Update conversion settings for an ad account", "tags": [ "ad-accounts" ], "description": "Persists the default conversion event for the requested Meta ad account so campaign creation can preselect the team-approved conversion settings. `default_conversion_pixel_id` has patch semantics: omitted leaves the stored pixel untouched, a string sets it, an explicit null clears it. The response always returns the resulting stored settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "default_conversion_event" ], "properties": { "default_conversion_event": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_conversion_pixel_id": { "description": "Omitted: the stored pixel id is left untouched. String: sets the default pixel. Explicit null: clears it.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "default_conversion_event", "default_conversion_pixel_id" ], "properties": { "default_conversion_event": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_conversion_pixel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/extended": { "get": { "operationId": "getExtendedAdAccounts", "summary": "Get extended ad account info from Meta", "tags": [ "ad-accounts" ], "description": "Fetches extended financial info (spend cap, amount spent, balance, payment method) from Meta Batch API for all ad accounts of the authenticated user. `accounts` is a map keyed by Meta account_id; when no tokens/eligible accounts are present it may be emitted as an empty collection.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "accounts" ], "properties": { "accounts": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "required": [ "account_id", "account_status", "spend_cap", "amount_spent", "balance", "funding_type", "funding_label", "funding_display", "currency" ], "properties": { "account_id": { "type": "string" }, "account_status": { "type": "integer" }, "spend_cap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "amount_spent": { "type": "number" }, "balance": { "type": "number" }, "funding_type": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "funding_label": { "type": "string" }, "funding_display": { "type": "string" }, "currency": { "type": "string" } } } }, { "maxItems": 0, "type": "array", "items": { "type": "object", "required": [ "account_id", "account_status", "spend_cap", "amount_spent", "balance", "funding_type", "funding_label", "funding_display", "currency" ], "properties": { "account_id": { "type": "string" }, "account_status": { "type": "integer" }, "spend_cap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "amount_spent": { "type": "number" }, "balance": { "type": "number" }, "funding_type": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "funding_label": { "type": "string" }, "funding_display": { "type": "string" }, "currency": { "type": "string" } } } } ] }, "skipped": { "type": "object", "required": [ "noToken" ], "properties": { "noToken": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts": { "get": { "operationId": "getApiV1AdAccounts", "summary": "Get ad accounts (server-side paginated)", "tags": [ "ad-accounts" ], "description": "Returns a server-side paginated, filtered, sorted list of Meta Ad Accounts. Supports offset pagination, search, and multiple filter dimensions. Results are scoped to the active workspace: accounts stamped with a team of the active scope plus legacy rows owned by accessible sessions.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "member_id", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "account_name" ] }, { "type": "string", "enum": [ "business_name" ] }, { "type": "string", "enum": [ "connected" ] }, { "type": "string", "enum": [ "account_status" ] }, { "type": "string", "enum": [ "account_currency" ] }, { "type": "string", "enum": [ "account_timezone_offset_hours_utc" ] }, { "type": "string", "enum": [ "amount_spent" ] }, { "type": "string", "enum": [ "ownership_type" ] }, { "type": "string", "enum": [ "created_at" ] }, { "type": "string", "enum": [ "updated_at" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_order", "required": false }, { "schema": { "minLength": 2, "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "connected" ] }, { "type": "string", "enum": [ "disconnected" ] }, { "type": "string", "enum": [ "error" ] } ] }, "in": "query", "name": "connected", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "in": "query", "name": "account_status", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] }, "in": "query", "name": "is_active", "required": false }, { "schema": { "maxLength": 20, "type": "string" }, "in": "query", "name": "ownership_type", "required": false }, { "schema": { "maxLength": 1000, "type": "string" }, "in": "query", "name": "business_id", "required": false }, { "schema": { "maxLength": 10, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_to", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "updated_from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "updated_to", "required": false }, { "schema": { "maxLength": 10, "type": "string" }, "in": "query", "name": "platform", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "counts" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "account_id", "account_name", "business_id", "business_name", "connected", "is_active", "account_currency", "account_timezone", "account_timezone_offset_hours_utc", "created_at", "updated_at", "account_status", "spend_cap", "amount_spent", "balance", "funding_type", "funding_label", "funding_display", "extended_synced_at", "default_conversion_event", "default_conversion_pixel_id", "advantage_plus_eligible", "threads_placement_enabled", "ai_creative_enabled" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "business_id": { "type": "string" }, "business_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connected": { "type": "boolean" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "account_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_timezone_offset_hours_utc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "account_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "spend_cap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "amount_spent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "balance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "funding_type": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "funding_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "funding_display": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extended_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "ownership_type": { "type": "string" }, "platform": { "type": "string" }, "default_conversion_event": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_conversion_pixel_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sheet_id": { "type": "string" }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "member_email": { "type": "string" }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "advantage_plus_eligible": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "threads_placement_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ai_creative_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "session_id": { "format": "uuid", "type": "string" }, "auth_email": { "type": "string" }, "auth_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_active": { "type": "boolean" } } } }, "total": { "type": "integer" }, "counts": { "type": "object", "required": [ "total", "connected", "active" ], "properties": { "total": { "type": "integer" }, "connected": { "type": "integer" }, "active": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/health-map": { "get": { "operationId": "getApiV1AdAccountsHealthMap", "summary": "Get health map of ad accounts (healthy / tokens_expired / disconnected)", "tags": [ "ad-accounts" ], "description": "Returns a map keyed by Meta ad account id with the best actionable health state across accessible rows. Used by clients to avoid running campaign actions against disconnected accounts or accounts with expired tokens.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "enum": [ "healthy" ] }, { "type": "string", "enum": [ "tokens_expired" ] }, { "type": "string", "enum": [ "disconnected" ] } ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/businesses": { "get": { "operationId": "getApiV1AdAccountsBusinesses", "summary": "List businesses available for ad accounts", "tags": [ "ad-accounts" ], "description": "Returns distinct Meta Business Manager ids and names represented by ad accounts visible to the caller, respecting team/member scoping.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/currencies": { "get": { "operationId": "getApiV1AdAccountsCurrencies", "summary": "List currencies available for ad accounts", "tags": [ "ad-accounts" ], "description": "Returns distinct account currency codes from ad accounts visible to the caller so clients can populate account filters without scanning the full account list.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/{accountId}/custom-audiences": { "get": { "operationId": "getApiV1AdAccountsByAccountIdCustomAudiences", "summary": "Get custom audiences for an ad account", "tags": [ "ad-accounts" ], "description": "Fetches custom audiences from Meta Graph API for the specified ad account.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "accountId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "audiences" ], "properties": { "audiences": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "approximate_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approximate_count": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/assign-all": { "post": { "operationId": "postApiV1AdAccountsAssignAll", "summary": "Assign all eligible ad accounts across team members", "tags": [ "ad-accounts" ], "description": "Finds all ad accounts for the team, groups them by sheet_id, and assigns each group via the assign service. Accounts disabled on Meta are assigned too: skipping them made unlinking one irreversible.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connected": { "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "assigned", "skipped_disabled" ], "properties": { "assigned": { "type": "integer" }, "skipped_disabled": { "description": "Always 0. Disabled-on-Meta accounts are assigned like any other since 2026-09-01; kept so the response shape stays stable for existing SDK clients.", "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ad-accounts/connect": { "post": { "operationId": "postApiV1AdAccountsConnect", "summary": "Connect non-Meta ad accounts", "tags": [ "ad-accounts" ], "description": "Marks selected non-Meta platform ad accounts as connected for the authenticated user/team and publishes an ad_accounts asset event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_ids", "platform" ], "properties": { "account_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" } }, "platform": { "maxLength": 10, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "statusCode", "error", "message", "code", "resource", "current", "max", "plan" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "resource": { "type": "string" }, "current": { "type": "number" }, "max": { "type": "number" }, "plan": { "type": "string" } } }, { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } ] } } } } } } }, "/api/v1/ad-accounts/disconnect": { "post": { "operationId": "postApiV1AdAccountsDisconnect", "summary": "Disconnect non-Meta ad accounts", "tags": [ "ad-accounts" ], "description": "Marks selected non-Meta platform ad accounts as disconnected for the authenticated user/team and publishes an ad_accounts asset event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_ids", "platform" ], "properties": { "account_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" } }, "platform": { "maxLength": 10, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ads/{ad_id}/creative": { "get": { "operationId": "getAdCreativeFlat", "summary": "Get an ad creative (flat)", "tags": [ "campaigns" ], "description": "Fetches the creative of a Meta ad and normalizes it to a flat shape (primary text, headline, description, CTA, link, url_tags, media). Used to pre-fill the duplicate-ad creative override form.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "ad_id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ad_name", "page_id", "instagram_user_id", "primary_text", "headline", "description", "call_to_action", "link", "url_tags", "media_type" ], "properties": { "ad_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instagram_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "call_to_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url_tags": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "other" ] } ] }, "image_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "video_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ad-creatives/{adId}": { "get": { "operationId": "getAdCreative", "summary": "Get ad creative details", "tags": [ "ad-creatives" ], "description": "Fetches creative details for an ad from Meta API, including thumbnail, image, video source, and full picture. For video creatives it also mirrors the video node's read-only `is_ai_generated` flag as `meta_ai_recognized` (present only when Meta reports it; absent means unknown, not \"not AI\"). Falls back to DB-stored thumbnail if the API call fails. Shape tracks Meta Graph v25.0 and tolerates additional pass-through fields.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ad_account_id", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sheet_id", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ad_id", "creative" ], "properties": { "ad_id": { "type": "string" }, "creative": { "anyOf": [ { "type": "null" }, { "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "caption": { "type": "string" }, "link_url": { "type": "string" }, "image_url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "full_picture": { "type": "string" }, "video_id": { "type": "string" }, "video_url": { "type": "string" }, "video_proxy_url": { "type": "string" }, "meta_ai_recognized": { "type": "boolean" }, "call_to_action_type": { "type": "string" }, "effective_object_story_id": { "type": "string" }, "object_story_spec": { "type": "object", "properties": { "link_data": { "type": "object", "properties": { "call_to_action": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } }, "caption": { "type": "string" }, "description": { "type": "string" }, "link": { "type": "string" }, "message": { "type": "string" }, "name": { "type": "string" }, "video_id": { "type": "string" } } }, "video_data": { "type": "object", "properties": { "call_to_action": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } }, "message": { "type": "string" }, "title": { "type": "string" }, "video_id": { "type": "string" } } } } } } } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ad-creatives/{adId}/video": { "get": { "operationId": "getApiV1AdCreativesByAdIdVideo", "summary": "Stream ad video", "tags": [ "ad-creatives" ], "description": "Proxies the Meta video source to avoid CORS issues. Accepts JWT via Authorization header or ?token= query param for use in video tags. Response body is the raw video stream (typically video/mp4) and supports HTTP Range requests; error responses are JSON.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "token", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sheet_id", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_id", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Streamed ad video (typically video/mp4) with HTTP Range support.", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "video/webm": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ad-creatives/{adId}/thumbnail-url": { "get": { "operationId": "getApiV1AdCreativesByAdIdThumbnailUrl", "summary": "Get signed thumbnail proxy URL", "tags": [ "ad-creatives" ], "description": "Returns an HMAC-signed URL for the thumbnail proxy endpoint. The signed URL is valid for 1 hour and can be used directly in without Bearer auth.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ad_account_id", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ad-creatives/{adId}/thumbnail": { "get": { "operationId": "getApiV1AdCreativesByAdIdThumbnail", "summary": "Proxy ad thumbnail image", "tags": [ "ad-creatives" ], "description": "Fetches a fresh thumbnail from Meta API and streams the image to the client. Requires a valid HMAC signature via sig/exp query parameters.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "sig", "required": true }, { "schema": { "type": "number" }, "in": "query", "name": "exp", "required": true }, { "schema": { "minimum": 32, "maximum": 800, "type": "number" }, "in": "query", "name": "size", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "acct", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "responses": { "200": { "description": "Ad creative thumbnail image (proxied from Meta).", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/ads/{id}/edit-canonical": { "post": { "operationId": "postApiV1AdsByIdEditCanonical", "summary": "Build an inline canonical campaign for the Edit Ad editor", "tags": [ "ads" ], "description": "Resolves an existing ad (Meta, Snapchat, Taboola, Google, or TikTok — creative/item, ad set, campaign, account) and returns an `ads_only` canonical campaign prefilled for the campaign-creator pro mode editor. No `campaign_draft` row is created — the editor keeps the canonical inline and posts it back to `/edit-publish` when the user clicks Publish.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/adsets/{adsetId}/add-ad-canonical": { "post": { "operationId": "postApiV1AdsetsByAdsetIdAddAdCanonical", "summary": "Build an inline empty-ad canonical campaign for the Add Ad editor", "tags": [ "ads" ], "description": "Resolves an existing ad set (Meta, Snapchat, Taboola, Google, or TikTok — its parent campaign + account) and returns an `ads_only` canonical campaign with the campaign + ad set read-only and exactly one BLANK ad (no `platformId`) so the publish worker creates a brand-new ad under the reused campaign/ad set. No `campaign_draft` row is created — the editor keeps the canonical inline and posts it back to `/edit-publish`.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "adsetId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/campaigns/{campaignId}/add-adset-canonical": { "post": { "operationId": "postApiV1CampaignsByCampaignIdAddAdsetCanonical", "summary": "Build an inline add-ad-set canonical campaign for the Add Ad Set editor", "tags": [ "ads" ], "description": "Resolves an existing Meta campaign (its account + business + default page) and returns an `add_adset` canonical campaign with the campaign read-only and exactly one BRAND-NEW ad set (no `platformId`) carrying one BLANK ad, so the publish worker creates a new ad set under the live campaign. No `campaign_draft` row is created — the editor keeps the canonical inline and posts it back to `/campaigns/:campaignId/add-adset-publish`. Meta only.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "campaignId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "type": "string", "enum": [ "meta" ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/adsets/{adsetId}/duplicate-canonical": { "post": { "operationId": "postApiV1AdsetsByAdsetIdDuplicateCanonical", "summary": "Build an inline duplicate-ad-set canonical campaign for the editor", "tags": [ "ads" ], "description": "Reads an existing Meta ad set (and its ads) and returns an `add_adset` canonical campaign that DUPLICATES it: the parent campaign is reused (read-only) and the ad set + ads are BRAND-NEW (no platformId). The editor edits any field, then posts it back to /campaigns/:campaignId/add-adset-publish which CREATES the new ad set under the live campaign. Mirrors Meta duplicate→editor. No draft row. Meta only.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "adsetId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "type": "string", "enum": [ "meta" ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ads/{id}/edit-publish": { "post": { "operationId": "postApiV1AdsByIdEditPublish", "summary": "Publish an inline canonical campaign from the Edit Ad editor (no draft)", "tags": [ "ads" ], "description": "Accepts a canonical `ads_only` campaign in the body and dispatches it to the standard publish worker via SQS. No `campaign_draft` row is created — the resulting `campaign_publish_job` carries `campaign_draft_id = NULL` and `source = \"edit_ad\"`. Returns the publish job id + worker_run_id for status polling via `/api/v1/campaign-drafts/publish-jobs/:jobId`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] } ] }, "idempotency_key": { "maxLength": 255, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "publish_job_id", "worker_run_id" ], "properties": { "publish_job_id": { "format": "uuid", "type": "string" }, "worker_run_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/campaigns/{campaignId}/add-adset-publish": { "post": { "operationId": "postApiV1CampaignsByCampaignIdAddAdsetPublish", "summary": "Add new ad set(s) to a launched campaign", "tags": [ "ads" ], "description": "Accepts a canonical campaign with publishMode \"add_adset\" and dispatches it to the standard publish worker. The campaign is reused (platformId set); the worker CREATES the new ad set(s) (those without a platformId) and their ads under it. Meta only. No campaign_draft row is created (source = \"add_adset\"). Returns the publish job id + worker_run_id for polling.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "canonical", "platform" ], "properties": { "canonical": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "platform": { "type": "string", "enum": [ "meta" ] }, "idempotency_key": { "maxLength": 255, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "campaignId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "publish_job_id", "worker_run_id" ], "properties": { "publish_job_id": { "format": "uuid", "type": "string" }, "worker_run_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai-action-log": { "get": { "operationId": "getApiV1AiActionLog", "summary": "List AI action log entries (PRD-N6)", "tags": [ "ai-chat" ], "description": "Paginated read-only feed of `ai_action_log` rows scoped by the caller role. Used by /settings/team/ai-activity and ops tooling. Rows written by the internal backoffice copilot (`origin = \"admin_copilot\"`) are returned ONLY to platform staff (`super_admin`, `admin`); every other role — `owner` and `manager` included — sees product rows (`origin = \"wavo\"`) only.", "parameters": [ { "schema": { "minimum": 1, "maximum": 10000, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "page_size", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "user_id", "required": false }, { "schema": { "maxLength": 60, "type": "string" }, "in": "query", "name": "tool_name", "required": false }, { "schema": { "maxLength": 30, "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "to", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "page", "page_size", "total", "items" ], "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "tool_name", "entity_type", "entity_id", "entity_name", "status", "risk_level", "created_at", "confirmed_at", "confirmed_by", "second_approver_id", "executed_at", "closed_at" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "tool_name": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "risk_level": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "confirmed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "second_approver_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "executed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "closed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ai-memory/preferences": { "get": { "operationId": "getApiV1AiMemoryPreferences", "summary": "Get AI memory preferences", "tags": [ "ai-memory" ], "description": "Returns the authenticated user AI memory and response preferences with neutral model mode values.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model", "preferred_metrics" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "patch": { "operationId": "patchApiV1AiMemoryPreferences", "summary": "Update AI memory preferences", "tags": [ "ai-memory" ], "description": "Updates user AI memory, language, tone, response format, and preferred metric settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "currency_display": { "maxLength": 10, "type": "string" }, "custom_instructions": { "maxLength": 2000, "type": "string" }, "instructions": { "maxLength": 2000, "type": "string" }, "language": { "maxLength": 10, "type": "string" }, "memory_enabled": { "type": "boolean" }, "preferred_currency": { "maxLength": 10, "type": "string" }, "preferred_language": { "maxLength": 10, "type": "string" }, "preferred_metrics": { "maxItems": 20, "type": "array", "items": { "maxLength": 50, "type": "string" } }, "preferred_model": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] }, "response_format": { "maxLength": 50, "type": "string" }, "tone": { "maxLength": 50, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model", "preferred_metrics" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai/preferences": { "get": { "operationId": "getAiPreferences", "summary": "Get AI memory preferences", "tags": [ "ai-memory" ], "description": "Returns the authenticated user AI memory and response preferences with neutral model mode values.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model", "preferred_metrics" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "put": { "operationId": "updateAiPreferences", "summary": "Update AI memory preferences", "tags": [ "ai-memory" ], "description": "Updates user AI memory, language, tone, response format, and preferred metric settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "currency_display": { "maxLength": 10, "type": "string" }, "custom_instructions": { "maxLength": 2000, "type": "string" }, "instructions": { "maxLength": 2000, "type": "string" }, "language": { "maxLength": 10, "type": "string" }, "memory_enabled": { "type": "boolean" }, "preferred_currency": { "maxLength": 10, "type": "string" }, "preferred_language": { "maxLength": 10, "type": "string" }, "preferred_metrics": { "maxItems": 20, "type": "array", "items": { "maxLength": 50, "type": "string" } }, "preferred_model": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] }, "response_format": { "maxLength": 50, "type": "string" }, "tone": { "maxLength": 50, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model", "preferred_metrics" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai-memory/facts": { "get": { "operationId": "getApiV1AiMemoryFacts", "summary": "List AI memory facts", "tags": [ "ai-memory" ], "description": "Lists active project memory facts visible to the authenticated user, optionally scoped to a project.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "project_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "project_id", "user_id", "fact_type", "fact_key", "fact_value", "source_type", "source_id", "confidence", "is_active", "opted_out_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "fact_type": { "type": "string" }, "fact_key": { "type": "string" }, "fact_value": { "$comment": "json-value" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "post": { "operationId": "postApiV1AiMemoryFacts", "summary": "Save an AI memory fact", "tags": [ "ai-memory" ], "description": "Creates or updates a project memory fact for the current team scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fact_key", "fact_type", "fact_value" ], "properties": { "confidence": { "minimum": 0, "maximum": 1, "type": "number" }, "fact_key": { "maxLength": 160, "type": "string" }, "fact_type": { "maxLength": 50, "type": "string" }, "fact_value": { "$comment": "json-value" }, "project_id": { "format": "uuid", "type": "string" }, "source_id": { "format": "uuid", "type": "string" }, "source_type": { "maxLength": 50, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "project_id", "user_id", "fact_type", "fact_key", "fact_value", "source_type", "source_id", "confidence", "is_active", "opted_out_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "fact_type": { "type": "string" }, "fact_key": { "type": "string" }, "fact_value": { "$comment": "json-value" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai/projects/{id}/facts": { "get": { "operationId": "getApiV1AiProjectsByIdFacts", "summary": "List project memory facts", "tags": [ "ai-memory" ], "description": "Lists active AI memory facts associated with a specific chat project.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "project_id", "user_id", "fact_type", "fact_key", "fact_value", "source_type", "source_id", "confidence", "is_active", "opted_out_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "fact_type": { "type": "string" }, "fact_key": { "type": "string" }, "fact_value": { "$comment": "json-value" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "delete": { "operationId": "deleteApiV1AiProjectsByIdFacts", "summary": "Clear project memory facts", "tags": [ "ai-memory" ], "description": "Soft-deletes all active AI memory facts for a project and returns the affected row count.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "affected" ], "properties": { "affected": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai/projects/{id}/facts/{factId}": { "delete": { "operationId": "deleteApiV1AiProjectsByIdFactsByFactId", "summary": "Delete a project memory fact", "tags": [ "ai-memory" ], "description": "Soft-deletes a single AI memory fact by id within the current team scope.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "factId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "project_id", "user_id", "fact_type", "fact_key", "fact_value", "source_type", "source_id", "confidence", "is_active", "opted_out_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "fact_type": { "type": "string" }, "fact_key": { "type": "string" }, "fact_value": { "$comment": "json-value" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai-memory/team-credit-caps": { "get": { "operationId": "getApiV1AiMemoryTeamCreditCaps", "summary": "List team AI credit caps", "tags": [ "ai-memory" ], "description": "Returns monthly AI credit caps for members in the accessible team scope.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "member_user_id", "monthly_cap", "enforced", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "member_user_id": { "format": "uuid", "type": "string" }, "monthly_cap": { "type": "integer" }, "monthly_used": { "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enforced": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actual_monthly_used": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "put": { "operationId": "putApiV1AiMemoryTeamCreditCaps", "summary": "Upsert a team AI credit cap", "tags": [ "ai-memory" ], "description": "Creates or updates a monthly AI credit cap for a team member.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "member_user_id", "monthly_cap" ], "properties": { "enforced": { "type": "boolean" }, "member_user_id": { "format": "uuid", "type": "string" }, "monthly_cap": { "minimum": 0, "type": "integer" }, "team_id": { "format": "uuid", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "member_user_id", "monthly_cap", "enforced", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "member_user_id": { "format": "uuid", "type": "string" }, "monthly_cap": { "type": "integer" }, "monthly_used": { "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enforced": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actual_monthly_used": { "type": "integer" } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai-memory/team-credit-usage": { "get": { "operationId": "getApiV1AiMemoryTeamCreditUsage", "summary": "List team AI credit usage", "tags": [ "ai-memory" ], "description": "Returns current-month AI credit usage for members in the accessible team scope.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "team_id", "member_user_id", "role", "email", "name", "monthly_cap", "reserved_monthly_used", "enforced", "actual_monthly_used", "message_count" ], "properties": { "team_id": { "format": "uuid", "type": "string" }, "member_user_id": { "format": "uuid", "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "monthly_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "reserved_monthly_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "enforced": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "actual_monthly_used": { "type": "integer" }, "message_count": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/team/credit-usage": { "get": { "operationId": "getApiV1TeamCreditUsage", "summary": "List team credit usage", "tags": [ "ai-memory" ], "description": "Legacy alias returning current-month AI credit usage for team members.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "team_id", "member_user_id", "role", "email", "name", "monthly_cap", "reserved_monthly_used", "enforced", "actual_monthly_used", "message_count" ], "properties": { "team_id": { "format": "uuid", "type": "string" }, "member_user_id": { "format": "uuid", "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "monthly_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "reserved_monthly_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "enforced": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "actual_monthly_used": { "type": "integer" }, "message_count": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/team/credit-caps/{userId}": { "put": { "operationId": "putApiV1TeamCreditCapsByUserId", "summary": "Upsert a member AI credit cap", "tags": [ "ai-memory" ], "description": "Legacy alias for creating or updating a monthly AI credit cap for a team member.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "monthly_cap" ], "properties": { "enforced": { "type": "boolean" }, "monthly_cap": { "minimum": 0, "type": "integer" }, "team_id": { "format": "uuid", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "member_user_id", "monthly_cap", "enforced", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "member_user_id": { "format": "uuid", "type": "string" }, "monthly_cap": { "type": "integer" }, "monthly_used": { "type": "integer" }, "reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "enforced": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actual_monthly_used": { "type": "integer" } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/ai-suggestions/benchmark": { "get": { "operationId": "getApiV1AiSuggestionsBenchmark", "summary": "Get cross-team benchmarks for the current team", "tags": [ "ai-suggestions" ], "description": "Returns anonymized peer-cohort KPI distributions (P25/P50/P75, sample flag) for the current team's industry + spend-tier segment, with a roll-up fallback to coarser cohorts. Privacy-gated: a team only sees benchmarks when it has opted in (team.benchmark_opt_in). When not opted in, opted_in is false and cohorts is empty. Cohorts are k-anonymous (>= 20 distinct teams) by construction.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "opted_in", "segment", "cohorts" ], "properties": { "opted_in": { "description": "Whether the current team consented to cross-team benchmarks.", "type": "boolean" }, "segment": { "additionalProperties": false, "type": "object", "required": [ "industry", "spend_tier" ], "properties": { "industry": { "description": "Resolved industry for the current team.", "type": "string" }, "spend_tier": { "description": "Resolved monthly-spend band, or \"*\" when unknown.", "type": "string" } } }, "cohorts": { "description": "Anonymized peer cohorts for the team segment. Empty when the team has not opted in.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "metric_key", "platform", "period", "cohort_size", "p25", "p50", "p75", "sample_flag" ], "properties": { "metric_key": { "description": "KPI the distribution describes (e.g. \"roas\", \"cpa\").", "type": "string" }, "platform": { "description": "Ad platform, or \"*\" when the cohort is rolled up across platforms.", "type": "string" }, "period": { "description": "Reporting window encoded in the aggregate (e.g. \"last_30d\").", "type": "string" }, "cohort_size": { "description": "Distinct contributing teams (>= the k-anonymity floor).", "type": "integer" }, "p25": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p75": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sample_flag": { "description": "\"reliable\" or \"high_variance\" depending on cohort size.", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/benchmark/opt-in": { "post": { "operationId": "postApiV1AiSuggestionsBenchmarkOptIn", "summary": "Set cross-team benchmark consent for the current team", "tags": [ "ai-suggestions" ], "description": "Updates team.benchmark_opt_in for the requested team context. Opting in lets the team both contribute its anonymized data to and read from peer benchmark cohorts; opting out stops contribution and hides benchmarks. Restricted to super_admin/admin/owner/manager.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "opt_in" ], "properties": { "opt_in": { "description": "Desired consent state for cross-team benchmarks.", "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "opt_in" ], "properties": { "opt_in": { "description": "Persisted consent state after the update.", "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions": { "get": { "operationId": "getApiV1AiSuggestions", "summary": "List proactive Wavo suggestions", "tags": [ "ai-suggestions" ], "description": "Returns the team-visible proactive suggestions plus pending/unread counters and the last generation run. Each item now includes the nullable `template_id` and `automation_rule_id` deep-link hints.", "parameters": [ { "schema": { "maximum": 50, "minimum": 1, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] }, { "type": "string", "enum": [ "critical" ] } ] }, "in": "query", "name": "priority", "required": false }, { "schema": { "maxLength": 50, "type": "string" }, "in": "query", "name": "scope_type", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "seen" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "applied" ] } ] }, "in": "query", "name": "status", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "pending_count", "unread_count", "last_run" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "template_id", "automation_rule_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "automation_rule_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } }, "pending_count": { "type": "integer" }, "unread_count": { "type": "integer" }, "last_run": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/stats": { "get": { "operationId": "getApiV1AiSuggestionsStats", "summary": "Get proactive Wavo suggestion stats", "tags": [ "ai-suggestions" ], "description": "Returns proactive suggestion counters for the resolved team scope: a real team.id taken from the `x-team-id` header (wins when present) or from `x-active-scope: team:`, falling back to the caller’s primary team membership when neither header is sent.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "approved_total", "pending", "rejected_total", "unread" ], "properties": { "approved_total": { "type": "integer" }, "pending": { "type": "integer" }, "rejected_total": { "type": "integer" }, "unread": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/generate": { "post": { "operationId": "postApiV1AiSuggestionsGenerate", "summary": "Queue a proactive-suggestion generation job", "tags": [ "ai-suggestions" ], "description": "Queues proactive suggestion generation for the requested team context. The job runs asynchronously and the UI should poll the list endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "queued" ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/{id}/seen": { "post": { "operationId": "postApiV1AiSuggestionsByIdSeen", "summary": "Mark a proactive suggestion as seen", "tags": [ "ai-suggestions" ], "description": "Marks a visible proactive suggestion as seen within the requested team context.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "template_id", "automation_rule_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "automation_rule_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/{id}/approve": { "post": { "operationId": "postApiV1AiSuggestionsByIdApprove", "summary": "Approve a proactive suggestion", "tags": [ "ai-suggestions" ], "description": "Approves a visible proactive suggestion and dispatches its action when it is executable. Refused with 423 while WAVO autonomy is stopped (kill-switch down or paused) and with 403 when the caller is below the approver floor; `code` names which gate refused.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "job_id", "suggestion" ], "properties": { "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "navigation_only": { "type": "boolean" }, "suggestion": { "additionalProperties": true, "type": "object", "required": [ "id", "template_id", "automation_rule_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "automation_rule_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "423": { "description": "Response 423", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/ai-suggestions/{id}/reject": { "post": { "operationId": "postApiV1AiSuggestionsByIdReject", "summary": "Reject a proactive suggestion", "tags": [ "ai-suggestions" ], "description": "Rejects a visible proactive suggestion within the requested team context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "reason": { "maxLength": 1000, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "template_id", "automation_rule_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "template_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "automation_rule_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/analytics/kpi": { "get": { "operationId": "getAnalyticsKpi", "summary": "Get analytics KPI metrics", "tags": [ "analytics" ], "description": "Returns key performance indicators (spend, revenue, profit, ROAS, CPA, CPM, CTR) aggregated across all team campaigns for the given date range.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "minLength": 3, "maxLength": 3, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_from_date", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_to_date", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "spend", "revenue", "profit", "roas", "cpa", "cpm", "ctr", "impressions", "clicks", "conversions", "currency", "true_roas", "contribution_profit", "data_source", "data_quality" ], "properties": { "spend": { "type": "number" }, "revenue": { "type": "number" }, "profit": { "type": "number" }, "roas": { "type": "number" }, "cpa": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "conversions": { "type": "number" }, "currency": { "type": "string" }, "true_roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contribution_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "data_source": { "anyOf": [ { "type": "string", "enum": [ "shopify" ] }, { "type": "string", "enum": [ "woocommerce" ] }, { "type": "string", "enum": [ "keitaro_postback" ] }, { "type": "string", "enum": [ "manual_cogs" ] }, { "type": "null" } ] }, "data_quality": { "anyOf": [ { "type": "string", "enum": [ "full" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "estimated" ] }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/ad-metrics": { "get": { "operationId": "getAnalyticsAdMetrics", "summary": "Get raw ADV metric sums (Analytics v2)", "tags": [ "analytics" ], "description": "Returns raw ADV metric SUMS (spend, impressions, clicks, inline_link_clicks, add_to_cart, purchases, purchase_value, leads, reach, frequency) for the Analytics v2 page: aggregate totals + per-account rows + optional previous-period totals. Ratios (CPM/CTR/ROAS/CPA/CVR…) are derived client-side via weighted aggregation (Σnumerator / Σdenominator).", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "minLength": 3, "maxLength": 3, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_from_date", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_to_date", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "totals", "previous", "accounts" ], "properties": { "currency": { "type": "string" }, "totals": { "type": "object", "required": [ "spend", "impressions", "clicks", "inline_link_clicks", "add_to_cart", "purchases", "purchase_value", "leads", "reach", "frequency" ], "properties": { "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "inline_link_clicks": { "type": "number" }, "add_to_cart": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" }, "reach": { "type": "number" }, "frequency": { "type": "number" } } }, "previous": { "anyOf": [ { "type": "object", "required": [ "spend", "impressions", "clicks", "inline_link_clicks", "add_to_cart", "purchases", "purchase_value", "leads", "reach", "frequency" ], "properties": { "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "inline_link_clicks": { "type": "number" }, "add_to_cart": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" }, "reach": { "type": "number" }, "frequency": { "type": "number" } } }, { "type": "null" } ] }, "accounts": { "type": "array", "items": { "type": "object", "allOf": [ { "type": "object", "required": [ "spend", "impressions", "clicks", "inline_link_clicks", "add_to_cart", "purchases", "purchase_value", "leads", "reach", "frequency" ], "properties": { "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "inline_link_clicks": { "type": "number" }, "add_to_cart": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" }, "reach": { "type": "number" }, "frequency": { "type": "number" } } }, { "type": "object", "required": [ "ad_account_id", "account_name", "platform" ], "properties": { "ad_account_id": { "type": "string" }, "account_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "type": "string" } } } ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/ad-metrics-trend": { "get": { "operationId": "getAnalyticsAdMetricsTrend", "summary": "Get per-day, per-platform raw ADV metric sums (Analytics v2)", "tags": [ "analytics" ], "description": "Returns per-day, per-platform raw ADV metric SUMS (spend, impressions, clicks, inline_link_clicks, add_to_cart, purchases, purchase_value, leads, reach) from campaign_daily_insight for time-series charts. Ratios (CPM/CTR/ROAS/CPA/CVR…) and frequency are derived client-side.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "minLength": 3, "maxLength": 3, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_from_date", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_to_date", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "series" ], "properties": { "currency": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "required": [ "platform", "date", "spend", "impressions", "clicks", "inline_link_clicks", "add_to_cart", "purchases", "purchase_value", "leads", "reach" ], "properties": { "platform": { "type": "string" }, "date": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "inline_link_clicks": { "type": "number" }, "add_to_cart": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" }, "reach": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/geo": { "get": { "operationId": "getAnalyticsGeo", "summary": "Get per-country raw ADV metric sums (Analytics v2)", "tags": [ "analytics" ], "description": "Returns per-country raw ADV metric SUMS (spend, impressions, clicks, inline_link_clicks, add_to_cart, purchases, purchase_value, leads) from campaign_country_daily_insight for the Analytics v2 \"Geo\" view, ordered by spend DESC. `country` is the ISO-2 region code (e.g. \"IT\"). Ratios are derived client-side.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "minLength": 3, "maxLength": 3, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_from_date", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_to_date", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "countries" ], "properties": { "currency": { "type": "string" }, "countries": { "type": "array", "items": { "type": "object", "required": [ "country", "spend", "impressions", "clicks", "inline_link_clicks", "add_to_cart", "purchases", "purchase_value", "leads" ], "properties": { "country": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "inline_link_clicks": { "type": "number" }, "add_to_cart": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/spend-trend": { "get": { "operationId": "getAnalyticsSpendTrend", "summary": "Get daily spend/revenue/profit trend", "tags": [ "analytics" ], "description": "Returns a day-by-day breakdown of spend, revenue, and profit for charting trends over the selected date range.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "minLength": 3, "maxLength": 3, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_from_date", "required": false }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "compare_to_date", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "days" ], "properties": { "days": { "type": "array", "items": { "type": "object", "required": [ "date", "spend", "revenue", "profit" ], "properties": { "date": { "type": "string" }, "spend": { "type": "number" }, "revenue": { "type": "number" }, "profit": { "type": "number" } } } }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "ad_account_id", "account_name", "days" ], "properties": { "ad_account_id": { "type": "string" }, "account_name": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "required": [ "date", "spend", "revenue", "profit" ], "properties": { "date": { "type": "string" }, "spend": { "type": "number" }, "revenue": { "type": "number" }, "profit": { "type": "number" } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/top-flop": { "get": { "operationId": "getAnalyticsTopFlop", "summary": "Get top and flop campaigns by metric", "tags": [ "analytics" ], "description": "Returns the best and worst performing campaigns ranked by a chosen metric (ROAS, CPA, CTR, or spend).", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "ctr" ] }, { "type": "string", "enum": [ "spend" ] } ] }, "in": "query", "name": "metric", "required": false }, { "schema": { "minimum": 1, "maximum": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "top", "flop" ], "properties": { "top": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "metric_value", "spend" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "metric_value": { "type": "number" }, "spend": { "type": "number" } } } }, "flop": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "metric_value", "spend" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "type": "string" }, "metric_value": { "type": "number" }, "spend": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/creative-performance": { "get": { "operationId": "getAnalyticsCreativePerformance", "summary": "Get creative (ad) performance ranking", "tags": [ "analytics" ], "description": "Returns a ranked list of ad creatives by the selected metric (CTR, CPA, or spend), including thumbnail URLs.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "ctr" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "spend" ] } ] }, "in": "query", "name": "metric", "required": false }, { "schema": { "minimum": 1, "maximum": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "ad_id", "ad_name", "thumbnail_url", "ctr", "cpa", "spend", "impressions", "clicks" ], "properties": { "ad_id": { "type": "string" }, "ad_name": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ctr": { "type": "number" }, "cpa": { "type": "number" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/spend-breakdown": { "get": { "operationId": "getAnalyticsSpendBreakdown", "summary": "Get spend breakdown by campaign", "tags": [ "analytics" ], "description": "Returns spend distribution across campaigns with percentage share, useful for pie/donut chart visualizations.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "minimum": 1, "maximum": 30, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "name", "value", "percentage" ], "properties": { "name": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/account-stats": { "get": { "operationId": "getAnalyticsAccountStats", "summary": "Get account health metrics (managed, active, disabled, ban rate, rejected ads)", "tags": [ "analytics" ], "description": "Returns aggregate account health stats including managed/active/disabled counts, ban rate, and rejected ad totals.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "platform", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "managed_accounts", "active_accounts", "disabled_accounts", "ban_rate", "rejected_ads", "total_ads" ], "properties": { "managed_accounts": { "type": "number" }, "active_accounts": { "type": "number" }, "disabled_accounts": { "type": "number" }, "ban_rate": { "type": "number" }, "rejected_ads": { "type": "number" }, "total_ads": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/channel-mix": { "get": { "operationId": "getCrossChannelMixTrend", "summary": "Get cross-channel channel mix trend", "tags": [ "analytics-cross-channel" ], "description": "Returns daily spend and spend-share percentages by platform for the requested cross-channel analytics window.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "since", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "until", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "platforms", "required": false }, { "schema": { "pattern": "^[A-Z]{3}$", "type": "string" }, "in": "query", "name": "target_currency", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "date", "platform", "share_pct", "spend" ], "properties": { "date": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "share_pct": { "type": "number" }, "spend": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/comparison": { "get": { "operationId": "getCrossChannelComparison", "summary": "Get cross-channel platform comparison", "tags": [ "analytics-cross-channel" ], "description": "Compares current and previous cross-channel analytics windows for each requested platform, including metric deltas.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "current_since", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "current_until", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "previous_since", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "previous_until", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "platforms", "required": false }, { "schema": { "pattern": "^[A-Z]{3}$", "type": "string" }, "in": "query", "name": "target_currency", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "current", "delta_pct", "platform", "previous" ], "properties": { "current": { "additionalProperties": false, "type": "object", "required": [ "clicks", "conversions", "cpa", "cpc", "cpm", "ctr", "impressions", "leads", "purchaseValue", "purchases", "revenue", "roas", "spend" ], "properties": { "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" } } }, "delta_pct": { "additionalProperties": false, "type": "object", "properties": { "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" } } }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "previous": { "additionalProperties": false, "type": "object", "required": [ "clicks", "conversions", "cpa", "cpc", "cpm", "ctr", "impressions", "leads", "purchaseValue", "purchases", "revenue", "roas", "spend" ], "properties": { "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/rules/templates": { "get": { "operationId": "listCrossPlatformRuleTemplates", "summary": "List cross-platform rule templates", "tags": [ "analytics-cross-channel" ], "description": "Returns the cross-platform automation templates whose required platforms are connected for the caller team.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "name_en", "name_it", "description_en", "description_it", "condition", "actions", "requires_platforms" ], "properties": { "id": { "type": "string" }, "name_en": { "type": "string" }, "name_it": { "type": "string" }, "description_en": { "type": "string" }, "description_it": { "type": "string" }, "condition": { "additionalProperties": false, "type": "object", "required": [ "type", "left", "operator", "right" ], "properties": { "type": { "type": "string", "enum": [ "cross_platform_comparison" ] }, "left": { "additionalProperties": false, "type": "object", "required": [ "type", "platform", "metric", "level", "timeframe_days" ], "properties": { "type": { "type": "string", "enum": [ "platform_metric" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "META" ] }, { "type": "string", "enum": [ "GOOGLE" ] }, { "type": "string", "enum": [ "TIKTOK" ] }, { "type": "string", "enum": [ "LINKEDIN" ] } ] }, "metric": { "anyOf": [ { "type": "string", "enum": [ "spend" ] }, { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "cpc" ] }, { "type": "string", "enum": [ "ctr" ] }, { "type": "string", "enum": [ "cpm" ] }, { "type": "string", "enum": [ "spend_pct" ] } ] }, "level": { "type": "string", "enum": [ "account" ] }, "timeframe_days": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 14 ] }, { "type": "number", "enum": [ 30 ] } ] }, "multiplier": { "type": "number" } } }, "operator": { "anyOf": [ { "type": "string", "enum": [ "greater_than" ] }, { "type": "string", "enum": [ "less_than" ] }, { "type": "string", "enum": [ "greater_or_equal" ] }, { "type": "string", "enum": [ "less_or_equal" ] }, { "type": "string", "enum": [ "equal" ] } ] }, "right": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "literal" ] }, "value": { "type": "number" } } }, { "additionalProperties": false, "type": "object", "required": [ "type", "platform", "metric", "level", "timeframe_days" ], "properties": { "type": { "type": "string", "enum": [ "platform_metric" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "META" ] }, { "type": "string", "enum": [ "GOOGLE" ] }, { "type": "string", "enum": [ "TIKTOK" ] }, { "type": "string", "enum": [ "LINKEDIN" ] } ] }, "metric": { "anyOf": [ { "type": "string", "enum": [ "spend" ] }, { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "cpc" ] }, { "type": "string", "enum": [ "ctr" ] }, { "type": "string", "enum": [ "cpm" ] }, { "type": "string", "enum": [ "spend_pct" ] } ] }, "level": { "type": "string", "enum": [ "account" ] }, "timeframe_days": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 14 ] }, { "type": "number", "enum": [ 30 ] } ] }, "multiplier": { "type": "number" } } } ] } } }, "actions": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "type", "platform", "entity_level" ], "properties": { "type": { "type": "string", "enum": [ "PAUSE_TOP_SPEND_CAMPAIGN" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "META" ] }, { "type": "string", "enum": [ "GOOGLE" ] }, { "type": "string", "enum": [ "TIKTOK" ] }, { "type": "string", "enum": [ "LINKEDIN" ] } ] }, "entity_level": { "type": "string", "enum": [ "campaign" ] } } }, { "additionalProperties": false, "type": "object", "required": [ "type", "platform", "entity_level", "pct" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "INCREASE_BUDGET_PCT" ] }, { "type": "string", "enum": [ "DECREASE_BUDGET_PCT" ] } ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "META" ] }, { "type": "string", "enum": [ "GOOGLE" ] }, { "type": "string", "enum": [ "TIKTOK" ] }, { "type": "string", "enum": [ "LINKEDIN" ] } ] }, "entity_level": { "type": "string", "enum": [ "campaign" ] }, "pct": { "type": "number" } } }, { "additionalProperties": false, "type": "object", "required": [ "type", "channel", "message_template" ], "properties": { "type": { "type": "string", "enum": [ "NOTIFY_CHANNEL" ] }, "channel": { "anyOf": [ { "type": "string", "enum": [ "in_app" ] }, { "type": "string", "enum": [ "email" ] }, { "type": "string", "enum": [ "telegram" ] } ] }, "message_template": { "type": "string" } } } ] } }, "requires_platforms": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "META" ] }, { "type": "string", "enum": [ "GOOGLE" ] }, { "type": "string", "enum": [ "TIKTOK" ] }, { "type": "string", "enum": [ "LINKEDIN" ] } ] } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/analytics/rules/from-template": { "post": { "operationId": "createCrossPlatformRuleFromTemplate", "summary": "Create automation rule from a cross-platform template", "tags": [ "analytics-cross-channel" ], "description": "Creates a paused automation rule from a template after verifying that the caller team has all required platforms connected and that optional schedule overrides are valid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "template_id" ], "properties": { "template_id": { "minLength": 1, "maxLength": 100, "type": "string" }, "name_override": { "minLength": 1, "maxLength": 200, "type": "string" }, "schedule_overrides": { "additionalProperties": false, "type": "object", "properties": { "interval_minutes": { "minimum": 15, "maximum": 1440, "type": "integer" }, "cooldown_minutes": { "minimum": 60, "maximum": 10080, "type": "integer" }, "max_executions_per_day": { "minimum": 1, "maximum": 10, "type": "integer" } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/analytics/export": { "post": { "operationId": "createUnifiedAnalyticsExport", "summary": "Create a unified cross-channel export job", "tags": [ "analytics-cross-channel" ], "description": "Creates a CSV or PDF export job. V1 rejects date ranges longer than 90 days.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "since", "until", "platforms", "format", "target_currency" ], "properties": { "since": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "until": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "platforms": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "minLength": 2, "maxLength": 20, "type": "string" } }, "format": { "anyOf": [ { "type": "string", "enum": [ "CSV" ] }, { "type": "string", "enum": [ "PDF" ] } ] }, "target_currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "timezone": { "maxLength": 100, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "job_id", "status" ], "properties": { "job_id": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "PENDING" ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/export/{job_id}": { "get": { "operationId": "getUnifiedAnalyticsExport", "summary": "Get unified cross-channel export job status", "tags": [ "analytics-cross-channel" ], "description": "Returns the current lifecycle state for a unified analytics export job and the download metadata once completed.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "job_id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "data", "error", "job_id", "status" ], "properties": { "data": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "format", "platforms", "since", "target_currency", "until" ], "properties": { "format": { "anyOf": [ { "type": "string", "enum": [ "CSV" ] }, { "type": "string", "enum": [ "PDF" ] } ] }, "platforms": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] } }, "since": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "target_currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "until": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "download_url", "format", "rows", "storage_key" ], "properties": { "download_url": { "format": "uri", "type": "string" }, "format": { "anyOf": [ { "type": "string", "enum": [ "CSV" ] }, { "type": "string", "enum": [ "PDF" ] } ] }, "rows": { "minimum": 0, "type": "integer" }, "storage_key": { "type": "string" } } }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "RUNNING" ] }, { "type": "string", "enum": [ "COMPLETED" ] }, { "type": "string", "enum": [ "FAILED" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/recommendation": { "get": { "operationId": "getCrossChannelRecommendation", "summary": "Get consultative cross-channel budget recommendation", "tags": [ "analytics-cross-channel" ], "description": "Returns the 30-day consultative budget mix recommendation and guardrail status for cross-channel analytics.", "parameters": [ { "schema": { "pattern": "^[A-Z]{3}$", "type": "string" }, "in": "query", "name": "target_currency", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "averageRoas", "guardrails", "perPlatform", "windowDays" ], "properties": { "averageRoas": { "type": "number" }, "guardrails": { "additionalProperties": false, "type": "object", "required": [ "passed", "reasons" ], "properties": { "passed": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "perPlatform": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "avgDailySpend", "current_budget_pct", "multiplier", "platform", "recommended_budget_pct", "recommendedBudgetDeltaPct", "roas", "spend", "suggestion_pct" ], "properties": { "avgDailySpend": { "type": "number" }, "current_budget_pct": { "type": "number" }, "multiplier": { "type": "number" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "recommended_budget_pct": { "type": "number" }, "recommendedBudgetDeltaPct": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" }, "suggestion_pct": { "type": "number" } } } }, "windowDays": { "type": "number", "enum": [ 30 ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/top-campaigns-cross-platform": { "get": { "operationId": "getTopCampaignsCrossPlatform", "summary": "Get top campaigns across platforms", "tags": [ "analytics-cross-channel" ], "description": "Returns ranked campaign performance across the requested platforms and date range using the selected metric.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "since", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "until", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "platforms", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "spend" ] }, { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "conversions" ] } ] }, "in": "query", "name": "metric", "required": false }, { "schema": { "minimum": 1, "maximum": 50, "default": 10, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "pattern": "^[A-Z]{3}$", "type": "string" }, "in": "query", "name": "target_currency", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "campaign_name", "clicks", "conversions", "cpa", "cpc", "cpm", "ctr", "impressions", "leads", "metric_value", "platform", "purchaseValue", "purchases", "revenue", "roas", "spend" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "metric_value": { "type": "number" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/analytics/unified": { "get": { "operationId": "getCrossChannelUnifiedAnalytics", "summary": "Get cross-channel unified analytics metrics", "tags": [ "analytics-cross-channel" ], "description": "Returns aggregated cross-channel KPI totals, per-platform KPI breakdowns, spend share and the latest included insight date.", "parameters": [ { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "since", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "until", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "platforms", "required": false, "description": "Comma-separated platform list." }, { "schema": { "pattern": "^[A-Z]{3}$", "type": "string" }, "in": "query", "name": "target_currency", "required": true }, { "schema": { "pattern": "^[A-Za-z0-9_/+-]+$", "type": "string" }, "in": "query", "name": "timezone", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "asOfDate", "perPlatform", "totals" ], "properties": { "asOfDate": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "perPlatform": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "platform", "clicks", "conversions", "cpa", "cpc", "cpm", "ctr", "impressions", "leads", "purchaseValue", "purchases", "revenue", "roas", "spend", "share_pct" ], "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" }, "share_pct": { "type": "number" } } } }, "totals": { "additionalProperties": false, "type": "object", "required": [ "clicks", "conversions", "cpa", "cpc", "cpm", "ctr", "impressions", "leads", "purchaseValue", "purchases", "revenue", "roas", "spend" ], "properties": { "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "ctr": { "type": "number" }, "impressions": { "type": "number" }, "leads": { "type": "number" }, "purchaseValue": { "type": "number" }, "purchases": { "type": "number" }, "revenue": { "type": "number" }, "roas": { "type": "number" }, "spend": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/api-keys": { "get": { "operationId": "getApiV1ApiKeys", "summary": "List API keys", "tags": [ "api-keys" ], "description": "Returns all API keys owned by the authenticated user (never returns the key itself).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "start", "prefix", "enabled", "permissions", "last_request", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "permissions": { "type": "object", "additionalProperties": { "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "last_request": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1ApiKeys", "summary": "Create API key", "tags": [ "api-keys" ], "description": "Generates a new M2M API key. The plain-text key is returned exactly ONCE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "permissions" ], "properties": { "name": { "minLength": 1, "maxLength": 64, "type": "string" }, "permissions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "expires_in_days": { "minimum": 1, "maximum": 365, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "key", "start", "prefix", "permissions", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "permissions": { "type": "object", "additionalProperties": { "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "statusCode", "error", "message", "code", "feature" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "feature": { "type": "string" } } }, { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/api-keys/{id}": { "patch": { "operationId": "patchApiV1ApiKeysById", "summary": "Update API key", "tags": [ "api-keys" ], "description": "Update name, permissions, or enabled flag. Setting enabled=false soft-revokes the key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 64, "type": "string" }, "permissions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "enabled": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "start", "prefix", "enabled", "permissions", "last_request", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "permissions": { "type": "object", "additionalProperties": { "uniqueItems": true, "type": "array", "items": { "type": "string" } } }, "last_request": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1ApiKeysById", "summary": "Delete API key", "tags": [ "api-keys" ], "description": "Permanently deletes an API key. For reversible revoke, PATCH enabled=false instead.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/asset-events/stream": { "get": { "operationId": "getApiV1AssetEventsStream", "summary": "Subscribe to asset events via SSE", "tags": [ "asset-events" ], "description": "Opens a long-lived Server-Sent Events (SSE) stream that emits asset lifecycle events (uploads, generations, deletions) for the authenticated session. The response never completes under normal operation - clients consume `data: \\n\\n` frames and rely on heartbeat comments (`:\\n\\n`) every 30s to keep the connection alive. This endpoint uses `reply.hijack()` and writes directly to the raw socket; the JSON response schemas declared by other routes do NOT apply here.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Server-Sent Events stream. Each frame is either a heartbeat comment (`:\\n\\n`) or a `data: \\n\\n` line whose payload is the JSON-serialized asset event published via `subscribeAssetEvents`.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Raw SSE frames. See the endpoint description for the JSON payload carried by each `data:` line." } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/audience-hub/comparison": { "post": { "operationId": "compareAudiencePerformance", "summary": "Compare audience performance", "tags": [ "audience-hub" ], "description": "Compares stored Audience Hub audiences over a date range and returns per-audience performance metrics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "platform", "audience_ids", "from_date", "to_date" ], "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] } ] }, "audience_ids": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "format": "uuid", "type": "string" } }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "rows" ], "properties": { "rows": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "audience_id", "audience_name", "spend", "impressions", "clicks", "conversions", "cpa", "ctr" ], "properties": { "audience_id": { "format": "uuid", "type": "string" }, "audience_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "conversions": { "type": "number" }, "cpa": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists": { "get": { "operationId": "listGoogleUserLists", "summary": "List Google Ads user lists", "tags": [ "audience-hub" ], "description": "Returns Google Ads audience user lists visible to the authenticated user, optionally filtered by account.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": true, "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "session_id": { "format": "uuid", "type": "string" }, "google_account_id": { "type": "string" }, "user_list_id": { "type": "string" }, "resource_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "list_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "upload_key_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membership_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size_for_display": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "size_for_search": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "origin_user_list_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists/sync": { "post": { "operationId": "syncGoogleUserLists", "summary": "Sync Google Ads user lists", "tags": [ "audience-hub" ], "description": "Fetches user lists from Google Ads for the requested account and stores the latest Audience Hub snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string" }, "login_customer_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "synced" ], "properties": { "synced": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists/crm": { "post": { "operationId": "createGoogleCrmUserList", "summary": "Create a Google Customer Match user list", "tags": [ "audience-hub" ], "description": "Creates a CRM-based Google Ads user list and stores the created resource in Audience Hub.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "name", "upload_key_type" ], "properties": { "account_id": { "type": "string" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "description": { "type": "string" }, "upload_key_type": { "anyOf": [ { "type": "string", "enum": [ "CONTACT_INFO" ] }, { "type": "string", "enum": [ "CRM_ID" ] }, { "type": "string", "enum": [ "MOBILE_ADVERTISING_ID" ] } ] }, "membership_life_span": { "minimum": 1, "maximum": 540, "type": "integer" }, "login_customer_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "resource_name", "user_list_id" ], "properties": { "resource_name": { "type": "string" }, "user_list_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists/lookalike": { "post": { "operationId": "createGoogleLookalikeUserList", "summary": "Create a Google lookalike user list", "tags": [ "audience-hub" ], "description": "Creates a Google Ads lookalike user list from one or more seed user lists.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "name", "seed_user_list_ids", "country_codes" ], "properties": { "account_id": { "type": "string" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "description": { "type": "string" }, "seed_user_list_ids": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "country_codes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "expansion_level": { "anyOf": [ { "type": "string", "enum": [ "NARROW" ] }, { "type": "string", "enum": [ "BALANCED" ] }, { "type": "string", "enum": [ "BROAD" ] } ] }, "login_customer_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "resource_name", "user_list_id" ], "properties": { "resource_name": { "type": "string" }, "user_list_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists/{user_list_id}": { "delete": { "operationId": "deleteGoogleUserList", "summary": "Delete a Google Ads user list", "tags": [ "audience-hub" ], "description": "Removes a Google Ads user list and soft-deletes the matching Audience Hub record when present.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "login_customer_id", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "user_list_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/google/user-lists/{user_list_id}/customer-match": { "post": { "operationId": "uploadGoogleCustomerMatch", "summary": "Upload Google Customer Match members", "tags": [ "audience-hub" ], "description": "Parses a CSV, uploads hashed identifiers to a Google Customer Match user list, and deletes the staged file.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "login_customer_id", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "user_list_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "job_resource_name", "uploaded", "parsed_rows", "invalid_lines" ], "properties": { "job_resource_name": { "type": "string" }, "uploaded": { "minimum": 0, "type": "integer" }, "parsed_rows": { "minimum": 0, "type": "integer" }, "invalid_lines": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV customer match file." } }, "additionalProperties": false } } } } } }, "/api/v1/audience-hub/insights/demographics": { "get": { "operationId": "getAudienceHubDemographics", "summary": "Audience Hub - demographic / geo / device breakdown (cross-provider, cached 24h)", "tags": [ "audience-hub" ], "description": "Returns cached or freshly fetched demographic, geo, or device breakdown rows for a connected ad account.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] } ] }, "in": "query", "name": "platform", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "external_account_id", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "campaign_id", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "adset_id", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "age_gender" ] }, { "type": "string", "enum": [ "geo" ] }, { "type": "string", "enum": [ "device" ] } ] }, "in": "query", "name": "breakdown", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "login_customer_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "data", "cache_hit" ], "properties": { "data": { "type": "array", "items": { "anyOf": [ { "additionalProperties": true, "type": "object", "properties": { "age": { "type": "string" }, "gender": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" }, "device_platform": { "type": "string" }, "impression_device": { "type": "string" }, "spend": { "type": "string" }, "impressions": { "type": "string" }, "clicks": { "type": "string" }, "reach": { "type": "string" }, "actions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "action_type", "value" ], "properties": { "action_type": { "type": "string" }, "value": { "type": "string" } } } }, "action_values": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "action_type", "value" ], "properties": { "action_type": { "type": "string" }, "value": { "type": "string" } } } } } }, { "additionalProperties": true, "type": "object", "properties": { "age_range": { "type": "string" }, "gender": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" }, "device": { "type": "string" }, "cost_micros": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "conversions": { "type": "number" }, "conversions_value": { "type": "number" } } }, { "additionalProperties": true, "type": "object", "properties": { "age": { "type": "string" }, "gender": { "type": "string" }, "country_code": { "type": "string" }, "province_id": { "type": "string" }, "placement": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "conversions": { "type": "number" } } }, { "additionalProperties": true, "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "conversions": { "type": "number" } } } ] } }, "cache_hit": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences": { "get": { "operationId": "listMetaAudiences", "summary": "List Meta custom audiences", "tags": [ "audience-hub" ], "description": "Returns Meta custom audiences visible to the authenticated user, optionally filtered by ad account.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": true, "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "session_id": { "format": "uuid", "type": "string" }, "meta_account_id": { "type": "string" }, "meta_audience_id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "audience_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subtype": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approximate_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "delivery_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule": { "$comment": "json-value" }, "origin_audience_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lookalike_spec": { "$comment": "json-value" }, "origin": { "type": "string" }, "source_catalog_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/sync": { "post": { "operationId": "syncMetaAudiences", "summary": "Sync Meta custom audiences", "tags": [ "audience-hub" ], "description": "Fetches custom audiences from Meta for the requested account and stores the latest Audience Hub snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "synced" ], "properties": { "synced": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/custom": { "post": { "operationId": "createMetaCustomAudience", "summary": "Create a Meta custom audience", "tags": [ "audience-hub" ], "description": "Creates a Meta customer-file custom audience and stores the created audience in Audience Hub.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "name" ], "properties": { "account_id": { "type": "string" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "description": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/website": { "post": { "operationId": "createMetaWebsiteAudience", "summary": "Create a Meta website audience", "tags": [ "audience-hub" ], "description": "Creates a Meta website custom audience using the supplied pixel rule JSON.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "name", "pixel_id", "rule" ], "properties": { "account_id": { "type": "string" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "pixel_id": { "type": "string" }, "rule": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "retention_days": { "minimum": 1, "maximum": 540, "type": "integer" }, "description": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/lookalike": { "post": { "operationId": "createMetaLookalikeAudience", "summary": "Create a Meta lookalike audience", "tags": [ "audience-hub" ], "description": "Creates a Meta lookalike audience from an origin custom audience.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "name", "origin_audience_id", "country" ], "properties": { "account_id": { "type": "string" }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "origin_audience_id": { "type": "string" }, "country": { "minLength": 2, "maxLength": 2, "type": "string" }, "ratio": { "minimum": 0.01, "maximum": 0.2, "type": "number" }, "type": { "anyOf": [ { "type": "string", "enum": [ "similarity" ] }, { "type": "string", "enum": [ "reach" ] } ] }, "description": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/{audience_id}": { "delete": { "operationId": "deleteMetaAudience", "summary": "Delete a Meta custom audience", "tags": [ "audience-hub" ], "description": "Deletes a Meta custom audience and soft-deletes the matching Audience Hub record.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "audience_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/meta/audiences/{audience_id}/customer-list": { "post": { "operationId": "uploadMetaCustomerList", "summary": "Upload Meta customer-list members", "tags": [ "audience-hub" ], "description": "Parses a CSV, hashes customer identifiers, uploads them to the Meta custom audience, and deletes the staged file.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "audience_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "received", "invalid", "parsed_rows", "invalid_lines" ], "properties": { "received": { "minimum": 0, "type": "integer" }, "invalid": { "minimum": 0, "type": "integer" }, "parsed_rows": { "minimum": 0, "type": "integer" }, "invalid_lines": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV customer list file." } }, "additionalProperties": false } } } } } }, "/api/v1/audience-hub/meta/audiences/overlap": { "post": { "operationId": "computeMetaAudienceOverlap", "summary": "Compute Meta audience overlap", "tags": [ "audience-hub" ], "description": "Returns Meta audience-overlap rows for two to five audience ids when the native endpoint is available.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "audience_ids" ], "properties": { "account_id": { "type": "string" }, "audience_ids": { "minItems": 2, "maxItems": 5, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "overlap" ], "properties": { "overlap": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "audience_id", "audience_name", "audience_size", "overlap_audiences" ], "properties": { "audience_id": { "type": "string" }, "audience_name": { "type": "string" }, "audience_size": { "type": "number" }, "overlap_audiences": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "audience_id", "audience_size", "ratio" ], "properties": { "audience_id": { "type": "string" }, "audience_size": { "type": "number" }, "ratio": { "type": "number" } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/scopes": { "get": { "operationId": "getAudienceHubScopes", "summary": "Audience Hub - scope status across all providers for the authenticated session", "tags": [ "audience-hub" ], "description": "Checks whether the authenticated user has the provider scopes required by Audience Hub features.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "ok", "platform", "missing" ], "properties": { "ok": { "type": "boolean" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] } ] }, "missing": { "type": "array", "items": { "type": "string" } }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_token" ] }, { "type": "string", "enum": [ "token_expired" ] }, { "type": "string", "enum": [ "missing_scope" ] }, { "type": "string", "enum": [ "not_supported" ] } ] }, "message": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/tiktok/audiences": { "get": { "operationId": "listTikTokAudiences", "summary": "List TikTok audiences", "tags": [ "audience-hub" ], "description": "Returns TikTok DMP audiences visible to the authenticated user, optionally filtered by advertiser.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "advertiser_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": true, "type": "object", "properties": { "id": { "format": "uuid", "type": "string" }, "session_id": { "format": "uuid", "type": "string" }, "advertiser_id": { "type": "string" }, "audience_id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "audience_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "audience_sub_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approximate_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "origin_audience_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/tiktok/audiences/sync": { "post": { "operationId": "syncTikTokAudiences", "summary": "Sync TikTok audiences", "tags": [ "audience-hub" ], "description": "Fetches TikTok custom audiences for the requested advertiser and stores the latest Audience Hub snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "advertiser_id" ], "properties": { "advertiser_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "synced" ], "properties": { "synced": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/tiktok/audiences/customer-file": { "post": { "operationId": "createTikTokCustomerFileAudience", "summary": "Create a TikTok customer-file audience", "tags": [ "audience-hub" ], "description": "Parses a CSV, uploads hashed identifiers to TikTok, and creates a customer-file audience.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "advertiser_id", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "custom_audience_name", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "EMAIL_SHA256" ] }, { "type": "string", "enum": [ "PHONE_SHA256" ] }, { "type": "string", "enum": [ "IDFA_SHA256" ] }, { "type": "string", "enum": [ "GAID_SHA256" ] }, { "type": "string", "enum": [ "EXTERNAL_ID" ] } ] }, "in": "query", "name": "calculate_type", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "custom_audience_id", "parsed_rows", "invalid_lines" ], "properties": { "custom_audience_id": { "type": "string" }, "parsed_rows": { "minimum": 0, "type": "integer" }, "invalid_lines": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/tiktok/audiences/lookalike": { "post": { "operationId": "createTikTokLookalikeAudience", "summary": "Create a TikTok lookalike audience", "tags": [ "audience-hub" ], "description": "Creates a TikTok lookalike audience from a source custom audience.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "advertiser_id", "custom_audience_name", "source_audience_id", "location_ids" ], "properties": { "advertiser_id": { "type": "string" }, "custom_audience_name": { "minLength": 1, "maxLength": 255, "type": "string" }, "source_audience_id": { "type": "string" }, "location_ids": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "lookalike_spec_type": { "anyOf": [ { "type": "string", "enum": [ "NARROW" ] }, { "type": "string", "enum": [ "BALANCE" ] }, { "type": "string", "enum": [ "BROAD" ] } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "custom_audience_id" ], "properties": { "custom_audience_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-hub/tiktok/audiences/{audience_id}": { "delete": { "operationId": "deleteTikTokAudience", "summary": "Delete a TikTok audience", "tags": [ "audience-hub" ], "description": "Deletes a TikTok custom audience and soft-deletes the matching Audience Hub record when present.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "advertiser_id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "audience_id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audience-saturation/alerts": { "get": { "operationId": "getApiV1AudienceSaturationAlerts", "summary": "List audience saturation alerts", "tags": [ "audience-saturation" ], "description": "Returns active audience saturation alerts visible to the caller. Set dismissed=true to include recently dismissed alerts.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "dismissed", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/audience-saturation/alerts/{id}/dismiss": { "patch": { "operationId": "patchApiV1AudienceSaturationAlertsByIdDismiss", "summary": "Dismiss audience saturation alert", "tags": [ "audience-saturation" ], "description": "Marks an audience saturation alert as dismissed when it belongs to a team accessible to the caller.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/audience-saturation/alerts/{id}/snooze": { "patch": { "operationId": "patchApiV1AudienceSaturationAlertsByIdSnooze", "summary": "Snooze audience saturation alert", "tags": [ "audience-saturation" ], "description": "Sets a snooze window on an audience saturation alert when it belongs to a team accessible to the caller.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "days" ], "properties": { "days": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 30 ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/market-intelligence/saturation-alerts": { "get": { "operationId": "getApiV1MarketIntelligenceSaturationAlerts", "summary": "List audience saturation alerts (legacy path)", "tags": [ "audience-saturation" ], "description": "Legacy alias for listing audience saturation alerts. Prefer GET /api/v1/audience-saturation/alerts for new clients.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "dismissed", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/market-intelligence/saturation-alerts/{id}/dismiss": { "patch": { "operationId": "patchApiV1MarketIntelligenceSaturationAlertsByIdDismiss", "summary": "Dismiss audience saturation alert (legacy path)", "tags": [ "audience-saturation" ], "description": "Legacy alias for dismissing an audience saturation alert. Prefer PATCH /api/v1/audience-saturation/alerts/{id}/dismiss for new clients.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/market-intelligence/saturation-alerts/{id}/snooze": { "patch": { "operationId": "patchApiV1MarketIntelligenceSaturationAlertsByIdSnooze", "summary": "Snooze audience saturation alert (legacy path)", "tags": [ "audience-saturation" ], "description": "Legacy alias for snoozing an audience saturation alert. Prefer PATCH /api/v1/audience-saturation/alerts/{id}/snooze for new clients.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "days" ], "properties": { "days": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 30 ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "session_id", "adset_id", "adset_name", "ad_account_id", "severity", "signals", "suggestion", "root_cause", "confidence_pct", "analysis_md", "baseline_window_days", "is_read", "is_dismissed", "dismissed_at", "detected_at", "resolved_at", "snoozed_until" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "adset_id": { "type": "string" }, "adset_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "severity": { "type": "string" }, "signals": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "root_cause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_pct": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "analysis_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseline_window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_read": { "type": "boolean" }, "is_dismissed": { "type": "boolean" }, "dismissed_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "detected_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "resolved_at": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] }, "snoozed_until": { "anyOf": [ { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/audit-log": { "get": { "operationId": "getApiV1AuditLog", "summary": "Get audit log", "tags": [ "audit" ], "description": "Returns paginated audit log entries for the team.", "parameters": [ { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "action", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to_date", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "user_email", "user_name", "action", "resource_type", "resource_id", "metadata", "ip_address", "user_agent", "created_at" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "user_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "action": { "type": "string" }, "resource_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/audit-log/export": { "get": { "operationId": "getApiV1AuditLogExport", "summary": "Export audit log as CSV", "tags": [ "audit" ], "description": "Exports audit log entries as a CSV file (max 1000 rows).", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "action", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to_date", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "CSV file content.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/setup": { "post": { "operationId": "postApiV1Auth2faSetup", "summary": "Start 2FA setup", "tags": [ "auth" ], "description": "Generates a new inactive TOTP secret and QR code for first-time 2FA setup. Account password is never required inside the app.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": {} } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret", "qr_code", "otpauth_url" ], "properties": { "secret": { "type": "string" }, "qr_code": { "type": "string" }, "otpauth_url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/verify": { "post": { "operationId": "postApiV1Auth2faVerify", "summary": "Verify TOTP and activate 2FA", "tags": [ "auth" ], "description": "Verifies the TOTP code from the authenticator app. On success, activates 2FA and returns backup codes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 6, "maxLength": 6, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "backup_codes" ], "properties": { "backup_codes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/disable": { "post": { "operationId": "postApiV1Auth2faDisable", "summary": "Remove TOTP authenticator factor", "tags": [ "auth" ], "description": "Requires TOTP/backup code to remove the authenticator-app factor. At least one passkey must already exist, so this endpoint can never leave the account without 2FA. Account password is never accepted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/validate": { "post": { "operationId": "postApiV1Auth2faValidate", "summary": "Validate 2FA during login", "tags": [ "auth" ], "description": "Verifies TOTP code or backup code after login when 2FA is enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkeys/register-options": { "get": { "operationId": "getApiV1Auth2faPasskeysRegisterOptions", "summary": "Generate passkey registration options", "tags": [ "auth" ], "description": "Generates WebAuthn registration options for adding a passkey as a 2FA method. The route is protected by the Wevion auth gate: missing-2FA users can enroll during setup, while existing 2FA users must already have passed the current-session challenge. Pass `replacingPasskeyId` when resetting an existing passkey so it is left out of `excludeCredentials` — otherwise the authenticator that already holds that credential rejects the new registration outright.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "replacingPasskeyId", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "challenge", "pubKeyCredParams", "rp", "user" ], "properties": { "attestation": { "type": "string" }, "authenticatorSelection": { "additionalProperties": false, "type": "object", "properties": { "authenticatorAttachment": { "type": "string" }, "requireResidentKey": { "type": "boolean" }, "residentKey": { "type": "string" }, "userVerification": { "type": "string" } } }, "challenge": { "type": "string" }, "excludeCredentials": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "public-key" ] } } } }, "extensions": { "type": "object", "additionalProperties": { "anyOf": [ { "$comment": "json-value" }, { "type": "array", "items": { "$comment": "json-value" } }, { "additionalProperties": { "$comment": "json-value" }, "type": "object", "properties": {} } ] } }, "pubKeyCredParams": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "alg", "type" ], "properties": { "alg": { "type": "number" }, "type": { "type": "string", "enum": [ "public-key" ] } } } }, "rp": { "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "timeout": { "type": "number" }, "user": { "additionalProperties": false, "type": "object", "required": [ "displayName", "id", "name" ], "properties": { "displayName": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkeys/register-verify": { "post": { "operationId": "postApiV1Auth2faPasskeysRegisterVerify", "summary": "Verify passkey registration", "tags": [ "auth" ], "description": "Verifies a WebAuthn registration response and stores the passkey as a 2FA method. On success it clears any support-reset re-enrollment flag and marks the current BetterAuth session as 2FA-verified.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "response" ], "properties": { "name": { "maxLength": 100, "type": "string" }, "response": { "additionalProperties": false, "type": "object", "required": [ "id", "rawId", "response", "type" ], "properties": { "authenticatorAttachment": { "type": "string" }, "clientExtensionResults": { "type": "object", "additionalProperties": { "anyOf": [ { "$comment": "json-value" }, { "type": "array", "items": { "$comment": "json-value" } }, { "additionalProperties": { "$comment": "json-value" }, "type": "object", "properties": {} } ] } }, "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "additionalProperties": false, "type": "object", "required": [ "attestationObject", "clientDataJSON" ], "properties": { "attestationObject": { "type": "string" }, "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "publicKey": { "type": "string" }, "publicKeyAlgorithm": { "type": "number" }, "transports": { "type": "array", "items": { "type": "string" } } } }, "type": { "type": "string", "enum": [ "public-key" ] } } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "backed_up", "created_at", "device_type", "id", "name" ], "properties": { "backed_up": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "device_type": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkey/options": { "get": { "operationId": "getApiV1Auth2faPasskeyOptions", "summary": "Generate passkey 2FA challenge", "tags": [ "auth" ], "description": "Generates WebAuthn authentication options for the current 2FA-pending session. The challenge is stored server-side and scoped to the BetterAuth session id.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "allowCredentials", "challenge", "rpId", "timeout", "userVerification" ], "properties": { "allowCredentials": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "public-key" ] } } } }, "challenge": { "type": "string" }, "rpId": { "type": "string" }, "timeout": { "type": "number" }, "userVerification": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkey/verify": { "post": { "operationId": "postApiV1Auth2faPasskeyVerify", "summary": "Verify passkey 2FA challenge", "tags": [ "auth" ], "description": "Verifies a WebAuthn passkey response for the current session and marks that BetterAuth session as second-factor verified. Also used, on an already-verified session, to satisfy the step-up requirement for passkey-management actions (e.g. DELETE /2fa/passkeys/:passkeyId): a short-lived single-use confirmation is stored and consumed there in place of a TOTP/backup code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "rawId", "response", "type" ], "properties": { "clientExtensionResults": { "type": "object", "additionalProperties": { "anyOf": [ { "$comment": "json-value" }, { "type": "array", "items": { "$comment": "json-value" } }, { "additionalProperties": { "$comment": "json-value" }, "type": "object", "properties": {} } ] } }, "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "additionalProperties": false, "type": "object", "required": [ "authenticatorData", "clientDataJSON", "signature" ], "properties": { "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" }, "userHandle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "type": { "type": "string", "enum": [ "public-key" ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkeys": { "get": { "operationId": "getApiV1Auth2faPasskeys", "summary": "List registered passkeys", "tags": [ "auth" ], "description": "Returns passkeys registered for the current user, for display in Security settings.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "backed_up", "created_at", "device_type", "id", "name" ], "properties": { "backed_up": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "device_type": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/passkeys/{passkeyId}": { "patch": { "operationId": "patchApiV1Auth2faPasskeysByPasskeyId", "summary": "Rename a registered passkey", "tags": [ "auth" ], "description": "Updates the display name of one passkey owned by the current user. Cosmetic only — no step-up required, since renaming can't weaken the account's 2FA posture.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "passkeyId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "backed_up", "created_at", "device_type", "id", "name" ], "properties": { "backed_up": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "device_type": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1Auth2faPasskeysByPasskeyId", "summary": "Remove a registered passkey", "tags": [ "auth" ], "description": "Deletes one passkey owned by the current user. The last passkey cannot be removed unless a TOTP authenticator is active, preserving the invariant that the account always has at least one 2FA method. If the account also has TOTP enabled, step-up is required: either a fresh TOTP/backup code in `code`, or a fresh passkey re-authentication via POST /2fa/passkey/verify (its short-lived confirmation is consumed here instead) — mirrors /2fa/disable, and gives passkey-related actions a passkey-based step-up option too, so a hijacked session cannot silently strip factors.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "passkeyId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/2fa/backup-codes": { "post": { "operationId": "postApiV1Auth2faBackupCodes", "summary": "Regenerate backup codes", "tags": [ "auth" ], "description": "Generates a new set of backup codes. Requires step-up authentication on top of the JWT session: the user must provide a valid current TOTP or one existing backup code. Account password is never accepted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "backup_codes" ], "properties": { "backup_codes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/claim-contact": { "post": { "operationId": "postApiV1AuthClaimContact", "summary": "Claim a contact identity", "tags": [ "auth" ], "description": "Attempts to link the authenticated user to a candidate identity, returning whether the claim linked immediately or requires verification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidate_user_session_id" ], "properties": { "candidate_user_session_id": { "format": "uuid", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "pending_verification" ] }, { "type": "string", "enum": [ "self_block" ] }, { "type": "string", "enum": [ "already_linked" ] }, { "type": "string", "enum": [ "forbidden_already_multi_linked" ] }, { "type": "string", "enum": [ "race_lost" ] } ] } } } } } }, "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "pending_verification" ] }, { "type": "string", "enum": [ "self_block" ] }, { "type": "string", "enum": [ "already_linked" ] }, { "type": "string", "enum": [ "forbidden_already_multi_linked" ] }, { "type": "string", "enum": [ "race_lost" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/auth/claim-verify": { "get": { "operationId": "getApiV1AuthClaimVerify", "summary": "Verify identity claim token", "tags": [ "auth" ], "description": "Consumes a one-time identity-claim verification token and reports whether the identity was linked.", "parameters": [ { "schema": { "minLength": 32, "maxLength": 128, "type": "string" }, "in": "query", "name": "token", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "race_lost" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "race_lost" ] } ] } } } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "linked" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "race_lost" ] } ] } } } } } } } } }, "/api/v1/auth/identity-candidates": { "get": { "operationId": "getApiV1AuthIdentityCandidates", "summary": "Find identity claim candidates", "tags": [ "auth" ], "description": "Looks up masked user identities that may match the provided email/name so an authenticated user can start a claim flow.", "parameters": [ { "schema": { "format": "email", "maxLength": 320, "type": "string" }, "in": "query", "name": "email", "required": true }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "name", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "candidates" ], "properties": { "candidates": { "type": "array", "items": { "type": "object", "required": [ "id", "email_masked", "name", "confidence_score", "confidence_level" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email_masked": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_score": { "type": "number" }, "confidence_level": { "anyOf": [ { "type": "string", "enum": [ "high" ] }, { "type": "string", "enum": [ "medium" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/auth/login-history": { "get": { "operationId": "getApiV1AuthLoginHistory", "summary": "Get login history", "tags": [ "auth" ], "description": "Returns paginated login history for the current user.", "parameters": [ { "schema": { "minimum": 1, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "page", "limit" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "ip_address", "user_agent", "login_method", "success", "failure_reason", "created_at", "country", "is_new_device", "is_new_country" ], "properties": { "id": { "type": "string" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "login_method": { "type": "string" }, "success": { "type": "boolean" }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_new_device": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_new_country": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/active-sessions": { "get": { "operationId": "getApiV1AuthActiveSessions", "summary": "Get active sessions", "tags": [ "auth" ], "description": "Returns the REAL non-expired BetterAuth sessions (auth_session rows) for the current user — one per signed-in device. The current device (`is_current`) is identified by the JWT `sid` claim (= auth_session.id, exposed as request.authSessionId); legacy tokens with no `sid` fall back to an IP + user-agent match. Revoking these truly logs out the corresponding device.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "ip_address", "user_agent", "login_method", "last_seen", "is_current" ], "properties": { "id": { "type": "string" }, "ip_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_agent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "login_method": { "type": "string" }, "last_seen": { "type": "string" }, "is_current": { "type": "boolean" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/revoke-sessions": { "post": { "operationId": "postApiV1AuthRevokeSessions", "summary": "Revoke all sessions", "tags": [ "auth" ], "description": "Logs out all devices, including the current one: deletes every BetterAuth session (auth_session row) for the user, denylists every sid in Redis for immediate JWT rejection, and sets token_invalidated_before=now so already-issued short-lived JWTs are rejected at once. Requires a current TOTP or backup code; account password is never accepted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "code" ], "properties": { "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/sessions/{sessionId}": { "delete": { "operationId": "deleteApiV1AuthSessionsBySessionId", "summary": "Revoke a single session", "tags": [ "auth" ], "description": "Truly revokes a specific device by deleting its BetterAuth session (auth_session row). The :sessionId is an auth_session.id (= the JWT `sid`). The session identified as current (sessionId === the caller’s sid) cannot be revoked here. The revoked sid is denylisted in Redis so the device’s outstanding short-lived JWT is rejected immediately.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sessionId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/account/delete": { "post": { "operationId": "postApiV1AuthAccountDelete", "summary": "Schedule account deletion", "tags": [ "auth" ], "description": "Schedules account for deletion after 30-day grace period. Requires typing \"DELETE\". Also requires a current TOTP or backup code; account password is never accepted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "confirmation", "code" ], "properties": { "confirmation": { "type": "string", "enum": [ "DELETE" ] }, "code": { "minLength": 6, "maxLength": 8, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "deletion_scheduled_at" ], "properties": { "message": { "type": "string" }, "deletion_scheduled_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/account/cancel-deletion": { "post": { "operationId": "postApiV1AuthAccountCancelDeletion", "summary": "Cancel account deletion", "tags": [ "auth" ], "description": "Cancels a previously scheduled account deletion.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/account/deletion-status": { "get": { "operationId": "getApiV1AuthAccountDeletionStatus", "summary": "Get account deletion status", "tags": [ "auth" ], "description": "Returns the current deletion schedule status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "scheduled", "deletion_scheduled_at" ], "properties": { "scheduled": { "type": "boolean" }, "deletion_scheduled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/security-nudge": { "get": { "operationId": "getApiV1AuthSecurityNudge", "summary": "Get 2FA nudge state", "tags": [ "auth" ], "description": "Returns the current user's 2FA-enable nudge banner state (last dismissal time, last shown time, snooze count). Defaults are returned when no state has been persisted yet.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "dismissed_at", "last_shown_at", "snooze_count" ], "properties": { "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_shown_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snooze_count": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "put": { "operationId": "putApiV1AuthSecurityNudge", "summary": "Update 2FA nudge state", "tags": [ "auth" ], "description": "Merges the provided fields into the current user's 2FA-enable nudge banner state and persists it. Used when the user snoozes (\"Più tardi\") or when the banner records that it was shown. Opt-in only; this never enforces 2FA.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "dismissed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "last_shown_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "snooze_count": { "minimum": 0, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "dismissed_at", "last_shown_at", "snooze_count" ], "properties": { "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_shown_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snooze_count": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/auth/me": { "get": { "operationId": "getApiV1AuthMe", "summary": "Get current user", "tags": [ "auth" ], "description": "Returns the authenticated user profile. Requires a valid JWT token. Includes `is_internal`: true when the profile is outside the clean analytics cohort (internal/staff e-mail domain, Gold/ULTRA, comped, allowlisted, backoffice staff role, or the demo account) — the same population every backoffice dashboard excludes. Used by the SPA to tag the session cohort in analytics; it carries no entitlement and grants nothing. Also includes `organization_id` (the backoffice `organization.id`), used by the SPA to tag the Clarity Live session for a direct backoffice lookup.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "email", "name", "role", "created_at", "last_login", "is_active", "company_name", "company_address", "company_city", "company_zip", "company_country", "company_vat", "team_name", "preferred_language", "avatar_url" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "last_login": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_vat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboarding_state": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "two_factor_enabled": { "type": "boolean" }, "two_factor_methods": { "additionalProperties": false, "type": "object", "required": [ "passkey", "totp" ], "properties": { "passkey": { "type": "boolean" }, "totp": { "type": "boolean" } } }, "two_factor_required": { "type": "boolean" }, "two_factor_setup_required": { "type": "boolean" }, "two_factor_reenroll_required": { "type": "boolean" }, "two_factor_rollout": { "additionalProperties": false, "type": "object", "required": [ "enabled", "is_enforced", "mandatory_after", "missing_policy", "rollout_started_at", "seconds_remaining" ], "properties": { "enabled": { "type": "boolean" }, "is_enforced": { "type": "boolean" }, "mandatory_after": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "missing_policy": { "type": "boolean" }, "rollout_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "seconds_remaining": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } }, "two_factor_mandatory": { "type": "boolean" }, "has_password": { "type": "boolean" }, "deletion_scheduled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_versions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "first_spend_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "is_internal": { "type": "boolean" }, "organization_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "subscription": { "type": "object", "required": [ "status", "is_read_only", "read_only_reason", "plan_name", "plan_display_name", "trial_end" ], "properties": { "status": { "type": "string" }, "is_read_only": { "type": "boolean" }, "read_only_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "plan_name": { "type": "string" }, "plan_display_name": { "type": "string" }, "trial_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "impersonation": { "additionalProperties": false, "type": "object", "required": [ "active", "impersonator" ], "properties": { "active": { "type": "boolean" }, "impersonator": { "anyOf": [ { "type": "object", "required": [ "id", "email", "role" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } }, { "type": "null" } ] } } }, "partner": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "partner_id", "status", "lane", "profile", "collection_mode", "partner_only", "panel_enabled", "public_profile_approved", "kyc_level", "payout_ready", "redirector_origin" ], "properties": { "partner_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "suspended" ] }, { "type": "string", "enum": [ "terminated" ] } ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "C1_creator" ] }, { "type": "string", "enum": [ "C2_community" ] }, { "type": "string", "enum": [ "C3_ugc" ] }, { "type": "string", "enum": [ "C4_newsletter" ] }, { "type": "string", "enum": [ "C5_referrer" ] }, { "type": "string", "enum": [ "C6_agency" ] }, { "type": "null" } ] }, "profile": { "anyOf": [ { "type": "string", "enum": [ "cliente-referrer" ] }, { "type": "string", "enum": [ "creator" ] }, { "type": "string", "enum": [ "ugc" ] }, { "type": "string", "enum": [ "closer" ] } ] }, "collection_mode": { "anyOf": [ { "type": "string", "enum": [ "cash" ] }, { "type": "string", "enum": [ "accrual" ] }, { "type": "string", "enum": [ "community_benefit" ] } ] }, "partner_only": { "type": "boolean" }, "panel_enabled": { "type": "boolean" }, "public_profile_approved": { "type": "boolean" }, "kyc_level": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "payout_ready": { "type": "boolean" }, "redirector_origin": { "type": "string" } } }, { "type": "null" } ] }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name", "app_install_source" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "app_install_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1AuthMe", "summary": "Update current user profile", "tags": [ "auth" ], "description": "Updates the authenticated user profile (name, company, language, onboarding_state). Requires a valid JWT token. If `onboarding_state.segment` is present it must be one of: agency, dtc, media_buyer, dropshipper, generic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "company_name": { "anyOf": [ { "minLength": 2, "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "company_address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "company_city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "company_zip": { "anyOf": [ { "minLength": 3, "maxLength": 20, "pattern": "^[A-Za-z0-9 \\-]{3,20}$", "type": "string" }, { "type": "null" } ] }, "company_country": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] }, "company_vat": { "anyOf": [ { "minLength": 5, "maxLength": 100, "pattern": "^[A-Za-z0-9 .\\-/]{5,100}$", "type": "string" }, { "type": "null" } ] }, "team_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "en" ] }, { "type": "string", "enum": [ "it" ] }, { "type": "string", "enum": [ "es" ] }, { "type": "string", "enum": [ "fr" ] }, { "type": "string", "enum": [ "de" ] }, { "type": "string", "enum": [ "pt" ] }, { "type": "string", "enum": [ "ja" ] }, { "type": "string", "enum": [ "ru" ] }, { "type": "string", "enum": [ "zh" ] }, { "type": "string", "enum": [ "ko" ] }, { "type": "string", "enum": [ "ar" ] }, { "type": "string", "enum": [ "hi" ] }, { "type": "string", "enum": [ "id" ] }, { "type": "string", "enum": [ "pl" ] }, { "type": "string", "enum": [ "ro" ] }, { "type": "string", "enum": [ "sr" ] }, { "type": "string", "enum": [ "th" ] }, { "type": "string", "enum": [ "tr" ] }, { "type": "string", "enum": [ "uk" ] } ] }, { "type": "null" } ] }, "onboarding_state": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "email", "name", "role", "created_at", "last_login", "is_active", "company_name", "company_address", "company_city", "company_zip", "company_country", "company_vat", "team_name", "preferred_language", "avatar_url" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "last_login": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_vat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboarding_state": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "two_factor_enabled": { "type": "boolean" }, "two_factor_methods": { "additionalProperties": false, "type": "object", "required": [ "passkey", "totp" ], "properties": { "passkey": { "type": "boolean" }, "totp": { "type": "boolean" } } }, "two_factor_required": { "type": "boolean" }, "two_factor_setup_required": { "type": "boolean" }, "two_factor_reenroll_required": { "type": "boolean" }, "two_factor_rollout": { "additionalProperties": false, "type": "object", "required": [ "enabled", "is_enforced", "mandatory_after", "missing_policy", "rollout_started_at", "seconds_remaining" ], "properties": { "enabled": { "type": "boolean" }, "is_enforced": { "type": "boolean" }, "mandatory_after": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "missing_policy": { "type": "boolean" }, "rollout_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "seconds_remaining": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } }, "two_factor_mandatory": { "type": "boolean" }, "has_password": { "type": "boolean" }, "deletion_scheduled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_versions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "first_spend_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "is_internal": { "type": "boolean" }, "organization_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "subscription": { "type": "object", "required": [ "status", "is_read_only", "read_only_reason", "plan_name", "plan_display_name", "trial_end" ], "properties": { "status": { "type": "string" }, "is_read_only": { "type": "boolean" }, "read_only_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "plan_name": { "type": "string" }, "plan_display_name": { "type": "string" }, "trial_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "impersonation": { "additionalProperties": false, "type": "object", "required": [ "active", "impersonator" ], "properties": { "active": { "type": "boolean" }, "impersonator": { "anyOf": [ { "type": "object", "required": [ "id", "email", "role" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } }, { "type": "null" } ] } } }, "partner": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "partner_id", "status", "lane", "profile", "collection_mode", "partner_only", "panel_enabled", "public_profile_approved", "kyc_level", "payout_ready", "redirector_origin" ], "properties": { "partner_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "suspended" ] }, { "type": "string", "enum": [ "terminated" ] } ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "C1_creator" ] }, { "type": "string", "enum": [ "C2_community" ] }, { "type": "string", "enum": [ "C3_ugc" ] }, { "type": "string", "enum": [ "C4_newsletter" ] }, { "type": "string", "enum": [ "C5_referrer" ] }, { "type": "string", "enum": [ "C6_agency" ] }, { "type": "null" } ] }, "profile": { "anyOf": [ { "type": "string", "enum": [ "cliente-referrer" ] }, { "type": "string", "enum": [ "creator" ] }, { "type": "string", "enum": [ "ugc" ] }, { "type": "string", "enum": [ "closer" ] } ] }, "collection_mode": { "anyOf": [ { "type": "string", "enum": [ "cash" ] }, { "type": "string", "enum": [ "accrual" ] }, { "type": "string", "enum": [ "community_benefit" ] } ] }, "partner_only": { "type": "boolean" }, "panel_enabled": { "type": "boolean" }, "public_profile_approved": { "type": "boolean" }, "kyc_level": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "payout_ready": { "type": "boolean" }, "redirector_origin": { "type": "string" } } }, { "type": "null" } ] }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name", "app_install_source" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "app_install_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/auth/accept-tos": { "post": { "operationId": "postApiV1AuthAcceptTos", "summary": "Accept Terms of Service", "tags": [ "auth" ], "description": "Records the user acceptance of the current legal documents. Accepts an optional per-document `documents[]` array (each version must match the current one); a legacy body with only `tos_version` accepts the whole current bundle. Writes an append-only row per document to the legal_consent ledger and updates the user acceptance state in one transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "tos_version" ], "properties": { "tos_version": { "minLength": 1, "maxLength": 10, "type": "string" }, "documents": { "minItems": 1, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "document", "version" ], "properties": { "document": { "anyOf": [ { "type": "string", "enum": [ "termsOfService" ] }, { "type": "string", "enum": [ "privacyPolicy" ] }, { "type": "string", "enum": [ "cookiePolicy" ] }, { "type": "string", "enum": [ "dataProcessingAgreement" ] }, { "type": "string", "enum": [ "acceptableUsePolicy" ] }, { "type": "string", "enum": [ "subProcessors" ] }, { "type": "string", "enum": [ "dataDeletion" ] } ] }, "version": { "minLength": 1, "maxLength": 20, "type": "string" } } } }, "method": { "anyOf": [ { "type": "string", "enum": [ "in_app" ] }, { "type": "string", "enum": [ "reconsent_prompt" ] }, { "type": "string", "enum": [ "signup_checkbox" ] } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "email", "name", "role", "created_at", "last_login", "is_active", "company_name", "company_address", "company_city", "company_zip", "company_country", "company_vat", "team_name", "preferred_language", "avatar_url" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "last_login": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_vat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboarding_state": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "two_factor_enabled": { "type": "boolean" }, "two_factor_methods": { "additionalProperties": false, "type": "object", "required": [ "passkey", "totp" ], "properties": { "passkey": { "type": "boolean" }, "totp": { "type": "boolean" } } }, "two_factor_required": { "type": "boolean" }, "two_factor_setup_required": { "type": "boolean" }, "two_factor_reenroll_required": { "type": "boolean" }, "two_factor_rollout": { "additionalProperties": false, "type": "object", "required": [ "enabled", "is_enforced", "mandatory_after", "missing_policy", "rollout_started_at", "seconds_remaining" ], "properties": { "enabled": { "type": "boolean" }, "is_enforced": { "type": "boolean" }, "mandatory_after": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "missing_policy": { "type": "boolean" }, "rollout_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "seconds_remaining": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } }, "two_factor_mandatory": { "type": "boolean" }, "has_password": { "type": "boolean" }, "deletion_scheduled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tos_accepted_versions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "first_spend_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "owner_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "is_internal": { "type": "boolean" }, "organization_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "subscription": { "type": "object", "required": [ "status", "is_read_only", "read_only_reason", "plan_name", "plan_display_name", "trial_end" ], "properties": { "status": { "type": "string" }, "is_read_only": { "type": "boolean" }, "read_only_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "plan_name": { "type": "string" }, "plan_display_name": { "type": "string" }, "trial_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "impersonation": { "additionalProperties": false, "type": "object", "required": [ "active", "impersonator" ], "properties": { "active": { "type": "boolean" }, "impersonator": { "anyOf": [ { "type": "object", "required": [ "id", "email", "role" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } }, { "type": "null" } ] } } }, "partner": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "partner_id", "status", "lane", "profile", "collection_mode", "partner_only", "panel_enabled", "public_profile_approved", "kyc_level", "payout_ready", "redirector_origin" ], "properties": { "partner_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "suspended" ] }, { "type": "string", "enum": [ "terminated" ] } ] }, "lane": { "anyOf": [ { "type": "string", "enum": [ "C1_creator" ] }, { "type": "string", "enum": [ "C2_community" ] }, { "type": "string", "enum": [ "C3_ugc" ] }, { "type": "string", "enum": [ "C4_newsletter" ] }, { "type": "string", "enum": [ "C5_referrer" ] }, { "type": "string", "enum": [ "C6_agency" ] }, { "type": "null" } ] }, "profile": { "anyOf": [ { "type": "string", "enum": [ "cliente-referrer" ] }, { "type": "string", "enum": [ "creator" ] }, { "type": "string", "enum": [ "ugc" ] }, { "type": "string", "enum": [ "closer" ] } ] }, "collection_mode": { "anyOf": [ { "type": "string", "enum": [ "cash" ] }, { "type": "string", "enum": [ "accrual" ] }, { "type": "string", "enum": [ "community_benefit" ] } ] }, "partner_only": { "type": "boolean" }, "panel_enabled": { "type": "boolean" }, "public_profile_approved": { "type": "boolean" }, "kyc_level": { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ] }, "payout_ready": { "type": "boolean" }, "redirector_origin": { "type": "string" } } }, { "type": "null" } ] }, "team": { "anyOf": [ { "type": "object", "required": [ "id", "name", "app_install_source" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "app_install_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/auth/change-password": { "post": { "operationId": "postApiV1AuthChangePassword", "summary": "Change or set password", "tags": [ "auth" ], "description": "Changes the authenticated user password. Requires current password verification when one exists. For SSO-only users with no local credential (e.g. Google sign-in) this endpoint sets the initial password and current_password is not required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "new_password" ], "properties": { "current_password": { "maxLength": 128, "type": "string" }, "new_password": { "minLength": 12, "maxLength": 128, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/auth/avatar": { "post": { "operationId": "postApiV1AuthAvatar", "summary": "Upload user avatar", "tags": [ "auth" ], "description": "Uploads a profile avatar image. Accepted formats: JPEG, PNG, WebP. Max 5MB. Image is resized to 256x256.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "avatar_url" ], "properties": { "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1AuthAvatar", "summary": "Delete user avatar", "tags": [ "auth" ], "description": "Removes the user profile avatar.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/auth/notifications": { "get": { "operationId": "getApiV1AuthNotifications", "summary": "[Deprecated] Get notification preferences", "tags": [ "auth" ], "description": "Deprecated. Use GET /api/v1/notifications/preferences instead. Returns email and browser notification settings.", "deprecated": true, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "email_reports", "email_errors", "browser_notifications" ], "properties": { "email_reports": { "type": "boolean" }, "email_errors": { "type": "boolean" }, "browser_notifications": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } }, "put": { "operationId": "putApiV1AuthNotifications", "summary": "[Deprecated] Update notification preferences", "tags": [ "auth" ], "description": "Deprecated. Use PUT /api/v1/notifications/preferences instead. Updates email and browser notification settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "email_reports", "email_errors", "browser_notifications" ], "properties": { "email_reports": { "type": "boolean" }, "email_errors": { "type": "boolean" }, "browser_notifications": { "type": "boolean" } } } } } }, "deprecated": true, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "email_reports", "email_errors", "browser_notifications" ], "properties": { "email_reports": { "type": "boolean" }, "email_errors": { "type": "boolean" }, "browser_notifications": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } } } } }, "/api/v1/beta-feedback/export": { "get": { "operationId": "getApiV1BetaFeedbackExport", "summary": "Export beta feedback as markdown", "tags": [ "beta-feedback" ], "description": "Generates a markdown file with all bug reports for Claude Code.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Markdown export content.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/beta-feedback/bugs": { "get": { "operationId": "getApiV1BetaFeedbackBugs", "summary": "List beta feedback bugs", "tags": [ "beta-feedback" ], "description": "Returns bug reports with optional filters.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "category", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "severity", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "number" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "category", "severity", "title", "description", "affected_page", "affected_component", "image_urls", "reporter_username", "reporter_name", "status", "developer_notes", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "category": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "affected_page": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "affected_component": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_urls": { "type": "array", "items": { "type": "string" } }, "reporter_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reporter_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "developer_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/beta-feedback/bugs/{id}": { "patch": { "operationId": "patchApiV1BetaFeedbackBugsById", "summary": "Update beta feedback bug", "tags": [ "beta-feedback" ], "description": "Update status or developer notes on a bug report.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "open" ] }, { "type": "string", "enum": [ "triaged" ] }, { "type": "string", "enum": [ "in_progress" ] }, { "type": "string", "enum": [ "fixed" ] }, { "type": "string", "enum": [ "wontfix" ] }, { "type": "string", "enum": [ "duplicate" ] } ] }, "developer_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/verify-checkout": { "post": { "operationId": "billingVerifyCheckout", "summary": "Verify Stripe Checkout session", "tags": [ "billing" ], "description": "Verifies a completed checkout session and creates the subscription if the webhook has not arrived yet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "stripe_session_id": { "type": "string" }, "session_id": { "type": "string" }, "user_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "verified" ], "properties": { "verified": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/checkout": { "post": { "operationId": "billingCreateCheckout", "summary": "Create Stripe Checkout session", "tags": [ "billing" ], "description": "Initiates a Stripe Checkout session for subscribing to a plan. Returns the checkout URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "plan_id", "interval" ], "properties": { "plan_id": { "format": "uuid", "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "monthly" ] }, { "type": "string", "enum": [ "annual" ] } ] }, "partner_code": { "description": "Opaque partner referral code carried from signup (Crockford base32, 8-20 chars).", "maxLength": 20, "minLength": 8, "pattern": "^[0-9A-HJKMNP-TV-Z]{8,20}$", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/bank-transfer/pay-now": { "post": { "operationId": "billingBankTransferPayNow", "summary": "Pay the annual plan now by bank transfer", "tags": [ "billing" ], "description": "Pays the ANNUAL EUR plan by SEPA bank transfer: Stripe issues an open invoice with virtual-IBAN payment instructions and the subscription stays active while the funds are in transit (trust window of BANK_TRANSFER_DUE_DAYS days, then the account is blocked if unpaid). While trialing, the trial ends immediately and the existing subscription is converted to plan_id (defaults to the current plan) — a trialing subscription can switch plan via this call, not just interval; switching to a plan with lower resource caps than the team currently uses is rejected with 400 DOWNGRADE_RESOURCE_LIMIT. With no live Stripe subscription (Free after trial, or canceled) a new send_invoice subscription is created for plan_id (defaults to the current plan) — re-subscribe by bank transfer cannot go through Checkout, which rejects customer_balance in subscription mode. Only available for EUR billing countries and when the bank-transfer feature flag is enabled — otherwise 409 BANK_TRANSFER_NOT_ELIGIBLE. Idempotent: re-calling inside an open trust window returns the existing open invoice URL for the SAME plan; a different plan_id while that window is open is rejected with 409 BANK_TRANSFER_NOT_ELIGIBLE instead of silently re-serving the old invoice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "plan_id": { "format": "uuid", "description": "Plan to buy (or switch to while trialing). Defaults to the current plan.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "invoice_url", "due_date" ], "properties": { "invoice_url": { "description": "Stripe hosted invoice page carrying the bank-transfer payment instructions.", "type": "string" }, "due_date": { "format": "date-time", "description": "When the invoice is due (end of the bank-transfer trust window).", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message", "code", "violations" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "DOWNGRADE_RESOURCE_LIMIT" ] }, "violations": { "type": "array", "items": { "type": "object", "required": [ "resource", "current", "limit" ], "properties": { "resource": { "type": "string" }, "current": { "type": "number" }, "limit": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "code" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "BANK_TRANSFER_NOT_ELIGIBLE" ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/cancel": { "post": { "operationId": "billingCancelSubscription", "summary": "Cancel subscription", "tags": [ "billing" ], "description": "Cancels the subscription. During trial: cancels at trial end. Paid: cancels at period end.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "cancel_at" ], "properties": { "cancel_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/reactivate": { "post": { "operationId": "billingReactivateSubscription", "summary": "Reactivate cancelled subscription", "tags": [ "billing" ], "description": "Removes cancel_at_period_end flag to reactivate a subscription that was set to cancel.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/change-plan": { "post": { "operationId": "postApiV1BillingChangePlan", "summary": "Change subscription plan", "tags": [ "billing" ], "description": "Changes the subscription to a different plan. Cooldown: max 1 downgrade per 7 days. Upgrades apply immediately; downgrades are deferred to the end of the current billing period (scheduled=true, effective_at set). Downgrades are rejected until usage fits the target plan limits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "plan_id", "interval" ], "properties": { "plan_id": { "format": "uuid", "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "monthly" ] }, { "type": "string", "enum": [ "annual" ] } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" }, "scheduled": { "type": "boolean" }, "effective_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object", "required": [ "resource", "current", "limit" ], "properties": { "resource": { "type": "string" }, "current": { "type": "number" }, "limit": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "next_change_at" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "next_change_at": { "format": "date-time", "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/plan-change-cooldown": { "get": { "operationId": "getApiV1BillingPlanChangeCooldown", "summary": "Check plan change cooldown", "tags": [ "billing" ], "description": "Returns whether the user can change plan and, if not, when the next change is available.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "can_change", "next_change_at" ], "properties": { "can_change": { "type": "boolean" }, "next_change_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/downgrade-preflight": { "get": { "operationId": "getApiV1BillingDowngradePreflight", "summary": "Downgrade preflight check", "tags": [ "billing" ], "description": "Read-only check of whether the team can downgrade to the given plan, or which connected resources / seats exceed that plan's caps. Reports a LIVE snapshot of quantities — it does NOT measure downstream consequences (OAuth tokens, sync history, active rules, CAPI dedup), and is not the enforcement gate: the change-plan call performs the authoritative block. Counts can drift between this check and the actual change.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "plan_id", "required": true, "description": "Target (lower) plan to downgrade to." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "can_downgrade", "violations" ], "properties": { "can_downgrade": { "description": "True when no connected-resource or seat count exceeds the target plan caps.", "type": "boolean" }, "violations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "resource", "current", "limit", "excess" ], "properties": { "resource": { "description": "Category over the cap: \"ad accounts\" | \"fan pages\" | \"pixels\" | \"catalogs\" | \"team members\".", "type": "string" }, "current": { "description": "Currently connected/used count for the team.", "type": "number" }, "limit": { "description": "Maximum the target plan allows.", "type": "number" }, "excess": { "description": "How many must be removed before the downgrade is allowed (current - limit).", "type": "number" } } } }, "seats_carried": { "description": "Purchased extra-user seats that will be carried onto the target plan (0 when none are carriable — those are then counted against the seat cap as a violation).", "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/downgrade-disconnectable": { "get": { "operationId": "getApiV1BillingDowngradeDisconnectable", "summary": "List disconnectable resources blocking a downgrade", "tags": [ "billing" ], "description": "Read-only. For each connected-resource category that exceeds the target plan's caps, lists the team's currently-connected instances the OWNER can choose to disconnect. Granular categories (ad accounts, fan pages) carry per-item handles; pixels/catalogs are returned as non_removable (the honest block stays — no first-class single-item disconnect / Outbrain detaches the whole session). Seat (team-member) violations are omitted (not a connected resource). LIVE snapshot — the change-plan call is the authoritative gate.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "plan_id", "required": true, "description": "Target (lower) plan to downgrade to." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "can_downgrade", "groups" ], "properties": { "can_downgrade": { "description": "True when nothing exceeds the target plan caps.", "type": "boolean" }, "groups": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "resource", "current", "limit", "excess", "capability", "items" ], "properties": { "resource": { "description": "Connected-resource category that exceeds the target plan cap.", "anyOf": [ { "type": "string", "enum": [ "ad_accounts" ] }, { "type": "string", "enum": [ "fan_pages" ] }, { "type": "string", "enum": [ "pixels" ] }, { "type": "string", "enum": [ "catalogs" ] } ] }, "current": { "type": "number" }, "limit": { "type": "number" }, "excess": { "description": "How many to remove (current - limit).", "type": "number" }, "capability": { "description": "\"granular\" → items can be disconnected one at a time (selector). \"non_removable\" (pixels/catalogs) → no per-item disconnect; the honest block stays.", "anyOf": [ { "type": "string", "enum": [ "granular" ] }, { "type": "string", "enum": [ "non_removable" ] } ] }, "items": { "description": "Team-owned connected instances; empty for non_removable categories.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "handle" ], "properties": { "label": { "type": "string" }, "handle": { "description": "Opaque handle identifying one removable connected resource (returned by the selector).", "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "kind", "sheet_id", "business_id", "ad_account_id" ], "properties": { "kind": { "type": "string", "enum": [ "meta_ad_account" ] }, "sheet_id": { "type": "string" }, "business_id": { "type": "string" }, "ad_account_id": { "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "kind", "sheet_id", "business_id", "fan_page_id" ], "properties": { "kind": { "type": "string", "enum": [ "meta_fan_page" ] }, "sheet_id": { "type": "string" }, "business_id": { "type": "string" }, "fan_page_id": { "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "kind", "platform", "connection_id" ], "properties": { "kind": { "type": "string", "enum": [ "platform_ad_account" ] }, "platform": { "maxLength": 10, "type": "string" }, "connection_id": { "format": "uuid", "type": "string" } } } ] } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/disconnect-resource": { "post": { "operationId": "postApiV1BillingDisconnectResource", "summary": "Disconnect one owner-chosen resource and re-run the downgrade preflight", "tags": [ "billing" ], "description": "Disconnects the single resource identified by `handle` (re-scoped to the caller's team via the platform's existing first-class disconnect path), then returns a fresh downgrade preflight for `plan_id`. Non-transactional by design: there is no rollback — the re-preflight is the authoritative post-state after every disconnect, so the client should always trust it over the boolean. A stale/foreign handle disconnects nothing (`disconnected:false`) and still returns a fresh preflight. WARNING: disconnecting has real downstream effects (OAuth tokens, sync history, active rules, CAPI dedup) the caller must surface.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "plan_id", "handle" ], "properties": { "plan_id": { "format": "uuid", "description": "Target (lower) plan being downgraded to.", "type": "string" }, "handle": { "description": "Opaque handle identifying one removable connected resource (returned by the selector).", "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "kind", "sheet_id", "business_id", "ad_account_id" ], "properties": { "kind": { "type": "string", "enum": [ "meta_ad_account" ] }, "sheet_id": { "type": "string" }, "business_id": { "type": "string" }, "ad_account_id": { "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "kind", "sheet_id", "business_id", "fan_page_id" ], "properties": { "kind": { "type": "string", "enum": [ "meta_fan_page" ] }, "sheet_id": { "type": "string" }, "business_id": { "type": "string" }, "fan_page_id": { "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "kind", "platform", "connection_id" ], "properties": { "kind": { "type": "string", "enum": [ "platform_ad_account" ] }, "platform": { "maxLength": 10, "type": "string" }, "connection_id": { "format": "uuid", "type": "string" } } } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "disconnected", "preflight" ], "properties": { "disconnected": { "description": "True when a team-owned connected resource was actually disconnected (false = stale/foreign handle).", "type": "boolean" }, "preflight": { "additionalProperties": false, "type": "object", "required": [ "can_downgrade", "violations" ], "properties": { "can_downgrade": { "description": "True when no connected-resource or seat count exceeds the target plan caps.", "type": "boolean" }, "violations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "resource", "current", "limit", "excess" ], "properties": { "resource": { "description": "Category over the cap: \"ad accounts\" | \"fan pages\" | \"pixels\" | \"catalogs\" | \"team members\".", "type": "string" }, "current": { "description": "Currently connected/used count for the team.", "type": "number" }, "limit": { "description": "Maximum the target plan allows.", "type": "number" }, "excess": { "description": "How many must be removed before the downgrade is allowed (current - limit).", "type": "number" } } } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/portal": { "post": { "operationId": "postApiV1BillingPortal", "summary": "Create Stripe Customer Portal session", "tags": [ "billing" ], "description": "Creates a Stripe Customer Portal session for managing billing. Returns the portal URL.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/payment-methods": { "get": { "operationId": "billingListPaymentMethods", "summary": "List saved payment methods", "tags": [ "billing" ], "description": "Returns the saved cards for the authenticated owner's Stripe customer (live from Stripe), each flagged with its default state and a validity status (valid/expired/expiring_soon).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "payment_methods", "has_active_subscription" ], "properties": { "payment_methods": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "brand", "last4", "exp_month", "exp_year", "is_default", "status" ], "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" }, "is_default": { "type": "boolean" }, "status": { "anyOf": [ { "type": "string", "enum": [ "valid" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "expiring_soon" ] } ] } } } }, "has_active_subscription": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/payment-methods/setup-intent": { "post": { "operationId": "billingCreatePaymentMethodSetupIntent", "summary": "Create a SetupIntent to add a card", "tags": [ "billing" ], "description": "Creates an off-session SetupIntent. The frontend confirms it with Stripe.js to collect and save a new card; the card attaches to the customer automatically on confirm.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "client_secret" ], "properties": { "client_secret": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/payment-methods/{id}": { "delete": { "operationId": "billingRemovePaymentMethod", "summary": "Remove a saved card", "tags": [ "billing" ], "description": "Detaches a saved card. Refuses with 409 last_card if it is the only card, or 409 default_in_use if it is the default while a subscription is active. Ownership is verified before any write.", "parameters": [ { "schema": { "pattern": "^pm_[A-Za-z0-9]+$", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "code" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "last_card" ] }, { "type": "string", "enum": [ "default_in_use" ] }, { "type": "string", "enum": [ "expired_card" ] } ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/payment-methods/{id}/default": { "post": { "operationId": "billingSetDefaultPaymentMethod", "summary": "Set a card as default", "tags": [ "billing" ], "description": "Sets the card as the customer's default payment method and, when a subscription is active, also as the subscription's default so renewals and off-session charges use it. Ownership is verified before any write.", "parameters": [ { "schema": { "pattern": "^pm_[A-Za-z0-9]+$", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message", "code" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "anyOf": [ { "type": "string", "enum": [ "last_card" ] }, { "type": "string", "enum": [ "default_in_use" ] }, { "type": "string", "enum": [ "expired_card" ] } ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/subscription": { "get": { "operationId": "getApiV1BillingSubscription", "summary": "Get current subscription", "tags": [ "billing" ], "description": "Returns the current subscription with plan details and usage for the authenticated user's team.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "id", "organization_id", "plan_id", "status", "billing_interval", "current_period_start", "current_period_end", "trial_start", "trial_end", "trial_eligible", "cancel_at_period_end", "extra_user_slots", "is_read_only", "is_unlimited", "has_billing_subscription", "read_only_reason", "billing_currency", "scheduled_plan_id", "scheduled_change_at", "bank_transfer", "plan" ], "properties": { "id": { "format": "uuid", "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "plan_id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "billing_interval": { "type": "string" }, "current_period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "trial_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "trial_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "trial_eligible": { "type": "boolean" }, "cancel_at_period_end": { "type": "boolean" }, "extra_user_slots": { "type": "number" }, "is_read_only": { "type": "boolean" }, "is_unlimited": { "type": "boolean" }, "has_billing_subscription": { "type": "boolean" }, "read_only_reason": { "anyOf": [ { "type": "string", "enum": [ "spend_exceeded" ] }, { "type": "string", "enum": [ "payment_failed" ] }, { "type": "string", "enum": [ "subscription_expired" ] }, { "type": "string", "enum": [ "demo_expired" ] }, { "type": "string", "enum": [ "canceled" ] }, { "type": "string", "enum": [ "account_deleted" ] }, { "type": "string", "enum": [ "past_due" ] }, { "type": "string", "enum": [ "unpaid" ] }, { "type": "string", "enum": [ "paused" ] }, { "type": "string", "enum": [ "incomplete" ] }, { "type": "string", "enum": [ "incomplete_expired" ] }, { "type": "string", "enum": [ "admin_suspended" ] }, { "type": "string", "enum": [ "bank_transfer_unpaid" ] }, { "maxLength": 50, "type": "string" }, { "type": "null" } ] }, "billing_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_plan_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "scheduled_change_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "bank_transfer": { "additionalProperties": false, "type": "object", "required": [ "eligible", "pending_until" ], "properties": { "eligible": { "description": "True when the annual plan can be paid now by SEPA bank transfer: feature flag ON, a payable state (status trialing, or no live Stripe subscription / canceled for a re-subscribe), and the billing country resolves to EUR.", "type": "boolean" }, "pending_until": { "description": "End of the bank-transfer trust window (access granted while funds are in transit); null when no transfer is pending.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, "plan": { "type": "object", "required": [ "id", "name", "display_name", "monthly_price_cents", "annual_price_cents", "max_users", "extra_user_price_cents", "max_ad_accounts", "max_fan_pages", "max_pixels", "max_catalogs", "max_ad_spend_cents", "sort_order", "is_published", "display_currency", "display_monthly_price_cents", "display_annual_price_cents", "data_retention_days", "sync_interval_minutes", "max_free_campaigns", "max_workspaces", "max_teams", "allow_white_label", "allow_multi_workspace", "allow_cross_platform", "allow_api_access", "ai_models_tier", "has_trial", "trial_days" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "monthly_price_cents": { "description": "Monthly price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "annual_price_cents": { "description": "Annual price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "max_users": { "description": "null = unlimited seats.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "extra_user_price_cents": { "description": "Extra user slot price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "max_ad_accounts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_fan_pages": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_pixels": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_catalogs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_ad_spend_cents": { "description": "Max 30-day ad spend quota in integer minor units of currency (cents for USD/EUR). Stored as Prisma Decimal and cast to integer.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sort_order": { "type": "number" }, "is_published": { "type": "boolean" }, "display_currency": { "type": "string" }, "display_monthly_price_cents": { "type": "integer" }, "display_annual_price_cents": { "type": "integer" }, "data_retention_days": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sync_interval_minutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_free_campaigns": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_workspaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_teams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "allow_white_label": { "type": "boolean" }, "allow_multi_workspace": { "type": "boolean" }, "allow_cross_platform": { "type": "boolean" }, "allow_api_access": { "type": "boolean" }, "ai_models_tier": { "type": "string" }, "has_trial": { "type": "boolean" }, "trial_days": { "type": "number" }, "max_api_keys": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_scheduled_reports": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_bulk_launch_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_competitor_watchlists": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_rule_ad_accounts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } }, { "type": "null" } ] } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/plans": { "get": { "operationId": "getApiV1BillingPlans", "summary": "List available plans", "tags": [ "billing" ], "description": "Returns all active plans sorted by sort_order.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "items" ], "properties": { "currency": { "description": "The currency resolved for this user (drives the display_* fields).", "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "display_name", "monthly_price_cents", "annual_price_cents", "max_users", "extra_user_price_cents", "max_ad_accounts", "max_fan_pages", "max_pixels", "max_catalogs", "max_ad_spend_cents", "sort_order", "is_published", "display_currency", "display_monthly_price_cents", "display_annual_price_cents", "data_retention_days", "sync_interval_minutes", "max_free_campaigns", "max_workspaces", "max_teams", "allow_white_label", "allow_multi_workspace", "allow_cross_platform", "allow_api_access", "ai_models_tier", "has_trial", "trial_days" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "monthly_price_cents": { "description": "Monthly price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "annual_price_cents": { "description": "Annual price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "max_users": { "description": "null = unlimited seats.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "extra_user_price_cents": { "description": "Extra user slot price in integer minor units of currency (cents for USD/EUR).", "type": "integer" }, "max_ad_accounts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_fan_pages": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_pixels": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_catalogs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_ad_spend_cents": { "description": "Max 30-day ad spend quota in integer minor units of currency (cents for USD/EUR). Stored as Prisma Decimal and cast to integer.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sort_order": { "type": "number" }, "is_published": { "type": "boolean" }, "display_currency": { "type": "string" }, "display_monthly_price_cents": { "type": "integer" }, "display_annual_price_cents": { "type": "integer" }, "data_retention_days": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sync_interval_minutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_free_campaigns": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_workspaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_teams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "allow_white_label": { "type": "boolean" }, "allow_multi_workspace": { "type": "boolean" }, "allow_cross_platform": { "type": "boolean" }, "allow_api_access": { "type": "boolean" }, "ai_models_tier": { "type": "string" }, "has_trial": { "type": "boolean" }, "trial_days": { "type": "number" }, "max_api_keys": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_scheduled_reports": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_bulk_launch_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_competitor_watchlists": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_rule_ad_accounts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/upgrade-from-demo": { "post": { "operationId": "postApiV1BillingUpgradeFromDemo", "summary": "Upgrade from demo plan", "tags": [ "billing" ], "description": "Deletes the demo subscription record so the user can subscribe to a paid plan.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/billing/payments": { "get": { "operationId": "getApiV1BillingPayments", "summary": "List payment history", "tags": [ "billing" ], "description": "Returns the payment history for the authenticated user's subscription.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount_cents", "currency", "status", "description", "invoice_pdf_url", "period_start", "period_end", "created_at" ], "properties": { "id": { "type": "string" }, "amount_cents": { "description": "Amount paid in integer minor units of currency (cents for USD/EUR). Sourced from Stripe amount_paid.", "type": "integer" }, "currency": { "description": "ISO 4217 currency code (uppercase), free-text passthrough. Sourced from the Stripe invoice currency (uppercased) or, on DB fallback, payment_history.currency (VarChar(3), uppercased-on-write). Runtime accepts any 3-letter code.", "type": "string" }, "status": { "description": "Invoice/payment status. 'draft'|'open'|'paid'|'void'|'uncollectible' mirror Stripe invoice.status; 'partially_refunded'|'refunded'|'disputed' are derived from persisted net-revenue reversal rows since Stripe keeps invoice.status='paid' after a refund/dispute.", "anyOf": [ { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "open" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "void" ] }, { "type": "string", "enum": [ "uncollectible" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "disputed" ] }, { "maxLength": 30, "type": "string" } ] }, "amount_refunded": { "minimum": 0, "description": "Amount refunded/disputed back in integer minor units, derived from the net-revenue reversal row keyed by stripe_invoice_id. Absent/0 when no reversal applies.", "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoice_pdf_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "period_start": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/usage": { "get": { "operationId": "getApiV1BillingUsage", "summary": "Get usage snapshot", "tags": [ "billing" ], "description": "Returns the usage snapshot for the authenticated user's team.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "id", "organization_id", "connected_ad_accounts", "connected_fan_pages", "connected_pixels", "connected_catalogs", "workspace_count", "team_member_count", "rolling_30d_spend_cents", "spend_currency", "spend_percentage", "computed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "organization_id": { "format": "uuid", "type": "string" }, "connected_ad_accounts": { "type": "number" }, "connected_fan_pages": { "type": "number" }, "connected_pixels": { "type": "number" }, "connected_catalogs": { "type": "number" }, "workspace_count": { "type": "number" }, "team_member_count": { "type": "number" }, "scheduled_report_count": { "type": "number" }, "competitor_watchlist_count": { "type": "number" }, "rolling_30d_spend_cents": { "description": "Rolling 30-day ad spend in integer minor units of currency (cents for USD/EUR). Stored as Prisma Decimal and cast to integer.", "type": "integer" }, "spend_currency": { "description": "ISO 4217 currency code of ad spend, free-text passthrough from the connected ad account (any currency). Runtime accepts any 3-letter code.", "type": "string" }, "spend_percentage": { "description": "Percentage of plan quota consumed (0-100+), two decimals.", "type": "number" }, "computed_at": { "format": "date-time", "type": "string" } } }, { "type": "null" } ] } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/organization-info": { "get": { "operationId": "billingGetOrganizationInfo", "summary": "Get organization billing profile", "tags": [ "billing" ], "description": "Returns the billing owner's organization billing/fiscal profile (legal name, VAT, billing email and address) used on invoices.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "legal_name", "vat_number", "billing_email", "billing_address", "billing_city", "billing_zip", "billing_country" ], "properties": { "legal_name": { "description": "Legal/company name (ragione sociale).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vat_number": { "description": "VAT / Tax ID / registration number.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_email": { "description": "Invoice recipient email.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_country": { "description": "ISO 3166-1 alpha-2 country code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "patch": { "operationId": "billingUpdateOrganizationInfo", "summary": "Update organization billing profile", "tags": [ "billing" ], "description": "Updates the billing/fiscal profile on the billing owner organization. Accepts any subset of fields; each is nullable to clear it. Values are trimmed and the country code is uppercased.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "legal_name": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "vat_number": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] }, "billing_email": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "billing_address": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "billing_city": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ] }, "billing_zip": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ] }, "billing_country": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "legal_name", "vat_number", "billing_email", "billing_address", "billing_city", "billing_zip", "billing_country" ], "properties": { "legal_name": { "description": "Legal/company name (ragione sociale).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vat_number": { "description": "VAT / Tax ID / registration number.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_email": { "description": "Invoice recipient email.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billing_country": { "description": "ISO 3166-1 alpha-2 country code.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/billing/extra-users": { "post": { "operationId": "postApiV1BillingExtraUsers", "summary": "Purchase extra user slots", "tags": [ "billing" ], "description": "Adds extra user slots to the current subscription via Stripe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "minimum": 1, "maximum": 25, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1BillingExtraUsers", "summary": "Remove extra user slots", "tags": [ "billing" ], "description": "Removes extra user slots from the current subscription.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "minimum": 1, "maximum": 25, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief": { "get": { "operationId": "getApiV1BriefingsByBriefingIdBrief", "summary": "Get active brief for a briefing", "tags": [ "campaign-by-context" ], "description": "Returns the active brief read model for a briefing workspace after validating ownership of the underlying chat project.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1BriefingsByBriefingIdBrief", "summary": "Create or get active brief for a briefing", "tags": [ "campaign-by-context" ], "description": "Initializes the active Campaign by Context brief for a briefing workspace, or returns the existing read model when it already exists.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1BriefingsByBriefingIdBrief", "summary": "Update brief sections via patch model", "tags": [ "campaign-by-context" ], "description": "Applies an optimistic-locking section patch to the canonical brief JSON and returns the updated read model.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "expected_version", "section", "payload" ], "properties": { "expected_version": { "minimum": 1, "type": "integer" }, "section": { "type": "string" }, "payload": { "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "source_type": { "anyOf": [ { "type": "string", "enum": [ "user_declared" ] }, { "type": "string", "enum": [ "document_grounded" ] }, { "type": "string", "enum": [ "ai_inferred" ] }, { "type": "string", "enum": [ "manual_edit" ] }, { "type": "string", "enum": [ "tracker_data" ] } ] }, "source_refs": { "type": "array", "items": { "type": "string" } }, "confidence": { "minimum": 0, "maximum": 1, "type": "number" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/tool-scope": { "patch": { "operationId": "patchApiV1BriefingsByBriefingIdBriefToolScope", "summary": "Update enabled Campaign by Context context tool scopes", "tags": [ "campaign-by-context" ], "description": "Replaces the allowed tool scope for the brief workspace and returns the updated brief read model.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "tool_scope" ], "properties": { "tool_scope": { "maxItems": 20, "type": "array", "items": { "maxLength": 64, "type": "string" } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/resource-selections": { "patch": { "operationId": "patchApiV1BriefingsByBriefingIdBriefResourceSelections", "summary": "Replace the brief context resource selections (connected platforms, assets, catalogs)", "tags": [ "campaign-by-context" ], "description": "Stores the selected connected resources for the brief context and returns the updated brief read model.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "resource_selections" ], "properties": { "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/recalculate-coverage": { "post": { "operationId": "postApiV1BriefingsByBriefingIdBriefRecalculateCoverage", "summary": "Recalculate brief coverage score", "tags": [ "campaign-by-context" ], "description": "Recomputes coverage and missing-field metadata from the current canonical brief JSON and returns the updated read model.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/complete": { "post": { "operationId": "postApiV1BriefingsByBriefingIdBriefComplete", "summary": "Complete brief (from DRAFT) and generate signed handoff artifact", "tags": [ "campaign-by-context" ], "description": "Transitions a draft brief to completed when coverage gates pass, generates the signed handoff artifact, and returns the completed read model.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/assemble-campaign": { "post": { "operationId": "postApiV1BriefingsByBriefingIdBriefAssembleCampaign", "summary": "Assemble a campaign draft from the brief", "tags": [ "campaign-by-context" ], "description": "Builds a canonical Meta campaign from the brief (one ad set per audience segment, one ad per creative concept), saves it as a PAUSED draft in the campaign editor, and reports whatever still blocks publishing. Never publishes.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "draft_id", "ad_set_count", "ad_count", "ready_to_publish", "blocking_issues" ], "properties": { "draft_id": { "format": "uuid", "type": "string" }, "ad_set_count": { "minimum": 0, "type": "integer" }, "ad_count": { "minimum": 0, "type": "integer" }, "ready_to_publish": { "type": "boolean" }, "blocking_issues": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "type": "string" }, "fieldPath": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/brief/reopen": { "post": { "operationId": "postApiV1BriefingsByBriefingIdBriefReopen", "summary": "Reopen completed brief to DRAFT for further editing", "tags": [ "campaign-by-context" ], "description": "Reopens a completed brief for editing, restores its documents if needed, and returns the draft read model.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "project_name", "status", "version", "schema_version", "brief", "coverage_score", "coverage_threshold", "dialog_stage", "missing_fields", "tool_scope", "section_statuses", "evidence_summary", "review_ready", "scope_context", "scope_type", "scope_brand_name", "resource_selections", "created_at", "updated_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "project_name": { "type": "string" }, "status": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "schema_version": { "type": "string" }, "brief": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "coverage_score": { "type": "number" }, "coverage_threshold": { "type": "number" }, "dialog_stage": { "type": "string" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "tool_scope": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "section_statuses": { "type": "object", "additionalProperties": { "type": "string" } }, "evidence_summary": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "review_ready": { "type": "boolean" }, "scope_context": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "scope_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/confidence/{fieldPath}/tier": { "get": { "operationId": "getApiV1BriefingsByBriefingIdConfidenceByFieldPathTier", "summary": "Get confidence tier for a brief field", "tags": [ "campaign-by-context" ], "description": "Returns the current confidence tier for one brief field path, or uncertain when no evidence exists.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "path", "name": "fieldPath", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "tier", "evidenceCount" ], "properties": { "tier": { "type": "string" }, "evidenceCount": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/confidence/tiers": { "get": { "operationId": "getApiV1BriefingsByBriefingIdConfidenceTiers", "summary": "Get all current field tiers for a brief", "tags": [ "campaign-by-context" ], "description": "Returns a field-path to confidence-tier map for the current evidence entries of a brief.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "tiers" ], "properties": { "tiers": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/confidence/conflicts": { "get": { "operationId": "getApiV1BriefingsByBriefingIdConfidenceConflicts", "summary": "List unresolved evidence conflicts on a brief", "tags": [ "campaign-by-context" ], "description": "Finds current brief fields that have competing evidence candidates and returns the candidates for manual resolution.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "conflicts" ], "properties": { "conflicts": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field_path", "candidates" ], "properties": { "field_path": { "type": "string" }, "candidates": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "entry_id", "value", "source_type", "observed_at", "confidence_tier" ], "properties": { "entry_id": { "format": "uuid", "type": "string" }, "value": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "source_type": { "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "confidence_tier": { "type": "string" } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/confidence/resolve": { "post": { "operationId": "postApiV1BriefingsByBriefingIdConfidenceResolve", "summary": "Resolve an evidence conflict on a brief by picking a winner", "tags": [ "campaign-by-context" ], "description": "Supersedes the current evidence value for a field with the selected winner entry and marks the new value as confirmed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "field_path", "winner_entry_id" ], "properties": { "field_path": { "minLength": 1, "maxLength": 200, "type": "string" }, "winner_entry_id": { "format": "uuid", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok", "new_entry_id" ], "properties": { "ok": { "type": "boolean" }, "new_entry_id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/confidence/{fieldPath}/evidence": { "get": { "operationId": "getApiV1BriefingsByBriefingIdConfidenceByFieldPathEvidence", "summary": "Get evidence trail for a brief field", "tags": [ "campaign-by-context" ], "description": "Returns the full evidence history for one brief field path, including superseded entries and validity windows.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "path", "name": "fieldPath", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "field_path", "field_value_json", "source_type", "source_refs", "confidence_score", "confidence_tier", "depth", "observed_at", "valid_from", "valid_to", "created_by" ], "properties": { "id": { "format": "uuid", "type": "string" }, "field_path": { "type": "string" }, "field_value_json": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "source_type": { "type": "string" }, "source_refs": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "confidence_tier": { "type": "string" }, "depth": { "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "valid_from": { "format": "date-time", "type": "string" }, "valid_to": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents/upload": { "post": { "operationId": "postApiV1BriefingsByBriefingIdDocumentsUpload", "summary": "Upload a document file to a briefing (multipart, single file)", "tags": [ "campaign-by-context" ], "description": "Accepts one multipart file up to 25 MB, stores it, finalizes the upload, and queues parsing for brief population.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "original_name", "mime_type", "size_bytes", "upload_status", "parse_status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "upload_status": { "type": "string" }, "parse_status": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents/init": { "post": { "operationId": "postApiV1BriefingsByBriefingIdDocumentsInit", "summary": "Initialize document upload for a briefing", "tags": [ "campaign-by-context" ], "description": "Creates the upload artifact and brief document join row before bytes are uploaded through a lower-level flow.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "original_name", "mime_type", "size_bytes" ], "properties": { "original_name": { "minLength": 1, "maxLength": 500, "type": "string" }, "mime_type": { "minLength": 1, "type": "string" }, "size_bytes": { "minimum": 1, "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "storage_key", "upload_status", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "storage_key": { "type": "string" }, "upload_status": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents/{id}/finalize": { "post": { "operationId": "postApiV1BriefingsByBriefingIdDocumentsByIdFinalize", "summary": "Finalize document upload and trigger parsing", "tags": [ "campaign-by-context" ], "description": "Marks an initialized document upload as uploaded and queues the asynchronous brief population parser.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "upload_status", "parse_status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "upload_status": { "type": "string" }, "parse_status": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents": { "get": { "operationId": "getApiV1BriefingsByBriefingIdDocuments", "summary": "List documents for a briefing", "tags": [ "campaign-by-context" ], "description": "Lists uploaded documents attached to the active brief in a briefing workspace.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "original_name", "mime_type", "size_bytes", "upload_status", "parse_status", "error_code", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "upload_status": { "type": "string" }, "parse_status": { "type": "string" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents/{id}": { "get": { "operationId": "getApiV1BriefingsByBriefingIdDocumentsById", "summary": "Get document details", "tags": [ "campaign-by-context" ], "description": "Returns upload and parsing metadata for one briefing document.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "original_name", "mime_type", "size_bytes", "upload_status", "parse_status", "error_code", "created_at", "updated_at", "extracted_text_ref" ], "properties": { "id": { "format": "uuid", "type": "string" }, "original_name": { "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "minimum": 0, "type": "integer" }, "upload_status": { "type": "string" }, "parse_status": { "type": "string" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "extracted_text_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1BriefingsByBriefingIdDocumentsById", "summary": "Delete a document from a briefing", "tags": [ "campaign-by-context" ], "description": "Soft-deletes a briefing document and its upload artifact, then attempts best-effort physical storage cleanup.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/documents/{id}/retry-parse": { "post": { "operationId": "postApiV1BriefingsByBriefingIdDocumentsByIdRetryParse", "summary": "Retry document parsing", "tags": [ "campaign-by-context" ], "description": "Resets a previously uploaded document to pending parse state and queues parsing again.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "parse_status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "parse_status": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/links": { "get": { "operationId": "getApiV1BriefingsByBriefingIdLinks", "summary": "List context links for a briefing", "tags": [ "campaign-by-context" ], "description": "Lists context links attached to the active brief in newest-first order.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "brief_intake_id", "url", "title", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brief_intake_id": { "format": "uuid", "type": "string" }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1BriefingsByBriefingIdLinks", "summary": "Add a context link/URL to a briefing", "tags": [ "campaign-by-context" ], "description": "Adds one validated http(s) context URL to the active brief after checking briefing ownership.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 1, "maxLength": 2048, "type": "string" }, "title": { "maxLength": 300, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "brief_intake_id", "url", "title", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brief_intake_id": { "format": "uuid", "type": "string" }, "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings/{briefingId}/links/{id}": { "delete": { "operationId": "deleteApiV1BriefingsByBriefingIdLinksById", "summary": "Remove a context link from a briefing", "tags": [ "campaign-by-context" ], "description": "Soft-deletes a context link from the active brief after checking briefing ownership.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/briefings": { "get": { "operationId": "getApiV1Briefings", "summary": "List briefings (Campaign by Context folders)", "tags": [ "campaign-by-context" ], "description": "Returns the current user briefings with their latest brief status and recent chat sessions. Supports status, search and offset pagination filters.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "all" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "briefing_id", "name", "created_at", "updated_at", "brief_id", "brief_status", "coverage_score", "recent_sessions" ], "properties": { "briefing_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "created_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "updated_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "coverage_score": { "type": "number" }, "recent_sessions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "title", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" } } } } } } }, "total": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiV1Briefings", "summary": "Create a new briefing (Campaign by Context folder)", "tags": [ "campaign-by-context" ], "description": "Creates a Campaign by Context briefing folder, initializes its draft brief and optionally persists tool scope and resource selections.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "tool_scope": { "maxItems": 20, "type": "array", "items": { "maxLength": 64, "type": "string" } }, "resource_selections": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "briefing_id", "brief_id", "name", "created_at" ], "properties": { "briefing_id": { "format": "uuid", "type": "string" }, "brief_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "created_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/briefings/{briefingId}": { "patch": { "operationId": "patchApiV1BriefingsByBriefingId", "summary": "Rename a briefing", "tags": [ "campaign-by-context" ], "description": "Renames a briefing folder owned by the current user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "briefing_id", "name", "updated_at" ], "properties": { "briefing_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "updated_at": { "format": "date-time", "description": "ISO 8601 UTC timestamp.", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1BriefingsByBriefingId", "summary": "Soft-delete a briefing with cascade", "tags": [ "campaign-by-context" ], "description": "Archives a briefing folder owned by the current user and soft-deletes its active brief and documents. Upload artifacts are left untouched.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefingId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools": { "get": { "operationId": "getApiV1BudgetPools", "summary": "List budget pools", "tags": [ "budget-pools" ], "description": "Returns budget allocation pools accessible to the authenticated user, including pool members.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "name", "ad_account_id", "currency", "daily_budget_cents", "allocation_frequency_h", "optimization_metric", "scoring_window_days", "min_budget_change_cents", "min_budget_change_pct", "min_member_budget_cents", "max_member_budget_cents", "status", "constraints", "last_allocated_at", "next_allocation_at", "created_at", "updated_at", "deleted_at", "members" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "daily_budget_cents": { "type": "integer" }, "allocation_frequency_h": { "type": "integer" }, "optimization_metric": { "type": "string" }, "scoring_window_days": { "type": "integer" }, "min_budget_change_cents": { "type": "integer" }, "min_budget_change_pct": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "min_member_budget_cents": { "type": "integer" }, "max_member_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "last_allocated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "next_allocation_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "members": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "entity_type", "entity_id", "entity_name", "ad_account_id", "min_budget_cents", "max_budget_cents", "weight", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "entity_type": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] }, { "type": "string" } ] }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "min_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1BudgetPools", "summary": "Create budget pool", "tags": [ "budget-pools" ], "description": "Creates a budget allocation pool and optional initial campaign or ad set members.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "dailyBudgetCents", "name" ], "properties": { "adAccountId": { "type": "string" }, "allocationFrequencyH": { "anyOf": [ { "type": "number", "enum": [ 4 ] }, { "type": "number", "enum": [ 8 ] }, { "type": "number", "enum": [ 12 ] }, { "type": "number", "enum": [ 24 ] } ] }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "currency": { "maxLength": 10, "type": "string" }, "dailyBudgetCents": { "minimum": 1, "type": "integer" }, "maxMemberBudgetCents": { "minimum": 0, "type": "integer" }, "members": { "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "entityId", "entityType" ], "properties": { "adAccountId": { "type": "string" }, "entityId": { "type": "string" }, "entityName": { "type": "string" }, "entityType": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] } ] }, "isActive": { "type": "boolean" }, "maxBudgetCents": { "minimum": 0, "type": "integer" }, "minBudgetCents": { "minimum": 0, "type": "integer" }, "weight": { "minimum": 0, "type": "number" } } } }, "minBudgetChangeCents": { "minimum": 0, "type": "integer" }, "minBudgetChangePct": { "minimum": 0, "type": "number" }, "minMemberBudgetCents": { "minimum": 0, "type": "integer" }, "name": { "maxLength": 255, "type": "string" }, "optimizationMetric": { "maxLength": 50, "type": "string" }, "scoringWindowDays": { "minimum": 1, "maximum": 30, "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "paused" ] } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "name", "ad_account_id", "currency", "daily_budget_cents", "allocation_frequency_h", "optimization_metric", "scoring_window_days", "min_budget_change_cents", "min_budget_change_pct", "min_member_budget_cents", "max_member_budget_cents", "status", "constraints", "last_allocated_at", "next_allocation_at", "created_at", "updated_at", "deleted_at", "members" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "daily_budget_cents": { "type": "integer" }, "allocation_frequency_h": { "type": "integer" }, "optimization_metric": { "type": "string" }, "scoring_window_days": { "type": "integer" }, "min_budget_change_cents": { "type": "integer" }, "min_budget_change_pct": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "min_member_budget_cents": { "type": "integer" }, "max_member_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "last_allocated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "next_allocation_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "members": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "entity_type", "entity_id", "entity_name", "ad_account_id", "min_budget_cents", "max_budget_cents", "weight", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "entity_type": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] }, { "type": "string" } ] }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "min_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}": { "get": { "operationId": "getApiV1BudgetPoolsById", "summary": "Get budget pool", "tags": [ "budget-pools" ], "description": "Returns one budget allocation pool with its members when it belongs to an accessible team.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "name", "ad_account_id", "currency", "daily_budget_cents", "allocation_frequency_h", "optimization_metric", "scoring_window_days", "min_budget_change_cents", "min_budget_change_pct", "min_member_budget_cents", "max_member_budget_cents", "status", "constraints", "last_allocated_at", "next_allocation_at", "created_at", "updated_at", "deleted_at", "members" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "daily_budget_cents": { "type": "integer" }, "allocation_frequency_h": { "type": "integer" }, "optimization_metric": { "type": "string" }, "scoring_window_days": { "type": "integer" }, "min_budget_change_cents": { "type": "integer" }, "min_budget_change_pct": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "min_member_budget_cents": { "type": "integer" }, "max_member_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "last_allocated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "next_allocation_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "members": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "entity_type", "entity_id", "entity_name", "ad_account_id", "min_budget_cents", "max_budget_cents", "weight", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "entity_type": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] }, { "type": "string" } ] }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "min_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1BudgetPoolsById", "summary": "Update budget pool", "tags": [ "budget-pools" ], "description": "Updates mutable settings for a budget allocation pool without changing its runtime allocation logic.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "adAccountId": { "type": "string" }, "allocationFrequencyH": { "anyOf": [ { "type": "number", "enum": [ 4 ] }, { "type": "number", "enum": [ 8 ] }, { "type": "number", "enum": [ 12 ] }, { "type": "number", "enum": [ 24 ] } ] }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "currency": { "maxLength": 10, "type": "string" }, "dailyBudgetCents": { "minimum": 1, "type": "integer" }, "maxMemberBudgetCents": { "minimum": 0, "type": "integer" }, "minBudgetChangeCents": { "minimum": 0, "type": "integer" }, "minBudgetChangePct": { "minimum": 0, "type": "number" }, "minMemberBudgetCents": { "minimum": 0, "type": "integer" }, "name": { "maxLength": 255, "type": "string" }, "optimizationMetric": { "maxLength": 50, "type": "string" }, "scoringWindowDays": { "minimum": 1, "maximum": 30, "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "paused" ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "name", "ad_account_id", "currency", "daily_budget_cents", "allocation_frequency_h", "optimization_metric", "scoring_window_days", "min_budget_change_cents", "min_budget_change_pct", "min_member_budget_cents", "max_member_budget_cents", "status", "constraints", "last_allocated_at", "next_allocation_at", "created_at", "updated_at", "deleted_at", "members" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "daily_budget_cents": { "type": "integer" }, "allocation_frequency_h": { "type": "integer" }, "optimization_metric": { "type": "string" }, "scoring_window_days": { "type": "integer" }, "min_budget_change_cents": { "type": "integer" }, "min_budget_change_pct": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "min_member_budget_cents": { "type": "integer" }, "max_member_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "constraints": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "last_allocated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "next_allocation_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "members": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "entity_type", "entity_id", "entity_name", "ad_account_id", "min_budget_cents", "max_budget_cents", "weight", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "entity_type": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] }, { "type": "string" } ] }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "min_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1BudgetPoolsById", "summary": "Delete budget pool", "tags": [ "budget-pools" ], "description": "Soft-deletes a budget allocation pool and deactivates its members.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/members": { "post": { "operationId": "postApiV1BudgetPoolsByIdMembers", "summary": "Add budget pool member", "tags": [ "budget-pools" ], "description": "Adds or reactivates a campaign or ad set member in a budget allocation pool.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "entityId", "entityType" ], "properties": { "adAccountId": { "type": "string" }, "entityId": { "type": "string" }, "entityName": { "type": "string" }, "entityType": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] } ] }, "isActive": { "type": "boolean" }, "maxBudgetCents": { "minimum": 0, "type": "integer" }, "minBudgetCents": { "minimum": 0, "type": "integer" }, "weight": { "minimum": 0, "type": "number" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "entity_type", "entity_id", "entity_name", "ad_account_id", "min_budget_cents", "max_budget_cents", "weight", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "entity_type": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "adset" ] }, { "type": "string" } ] }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "min_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "is_active": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/members/{memberId}": { "delete": { "operationId": "deleteApiV1BudgetPoolsByIdMembersByMemberId", "summary": "Remove budget pool member", "tags": [ "budget-pools" ], "description": "Deactivates a member in a budget allocation pool.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "memberId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/simulate": { "post": { "operationId": "postApiV1BudgetPoolsByIdSimulate", "summary": "Simulate budget allocation", "tags": [ "budget-pools" ], "description": "Calculates a what-if budget allocation for the pool and stores a simulation log entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "allocation", "dateRange", "diminishingReturns", "sourceConfidence" ], "properties": { "allocation": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currentBudgetCents", "entityId", "entityType", "currentSpendCents", "proposedBudgetCents", "score", "reason" ], "properties": { "currentBudgetCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "entityId": { "type": "string" }, "entityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "entityType": { "type": "string" }, "currentSpendCents": { "type": "integer" }, "proposedBudgetCents": { "type": "integer" }, "score": { "type": "number" }, "reason": { "type": "string" } } } }, "dateRange": { "additionalProperties": false, "type": "object", "required": [ "fromDate", "toDate", "wasClamped" ], "properties": { "fromDate": { "format": "date", "type": "string" }, "toDate": { "format": "date", "type": "string" }, "wasClamped": { "type": "boolean" } } }, "diminishingReturns": { "type": "object", "additionalProperties": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "dr_detected", "dr_score", "dr_threshold_eur", "recent_roas", "recent_spend", "previous_roas", "previous_spend" ], "properties": { "campaign_id": { "type": "string" }, "dr_detected": { "type": "boolean" }, "dr_score": { "type": "integer" }, "dr_threshold_eur": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recent_roas": { "type": "number" }, "recent_spend": { "type": "number" }, "previous_roas": { "type": "number" }, "previous_spend": { "type": "number" } } } }, "sourceConfidence": { "additionalProperties": false, "type": "object", "required": [ "platform_performance", "tracker" ], "properties": { "platform_performance": { "type": "number" }, "tracker": { "type": "number" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/allocate": { "post": { "operationId": "postApiV1BudgetPoolsByIdAllocate", "summary": "Execute budget allocation", "tags": [ "budget-pools" ], "description": "Queues or synchronously executes budget changes for a pool after WAVO guardrail checks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "async": { "default": true, "type": "boolean" }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "queued" ] } } }, { "type": "object", "allOf": [ { "additionalProperties": false, "type": "object", "required": [ "allocation", "dateRange", "diminishingReturns", "sourceConfidence" ], "properties": { "allocation": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currentBudgetCents", "entityId", "entityType", "currentSpendCents", "proposedBudgetCents", "score", "reason" ], "properties": { "currentBudgetCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "entityId": { "type": "string" }, "entityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "entityType": { "type": "string" }, "currentSpendCents": { "type": "integer" }, "proposedBudgetCents": { "type": "integer" }, "score": { "type": "number" }, "reason": { "type": "string" } } } }, "dateRange": { "additionalProperties": false, "type": "object", "required": [ "fromDate", "toDate", "wasClamped" ], "properties": { "fromDate": { "format": "date", "type": "string" }, "toDate": { "format": "date", "type": "string" }, "wasClamped": { "type": "boolean" } } }, "diminishingReturns": { "type": "object", "additionalProperties": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "dr_detected", "dr_score", "dr_threshold_eur", "recent_roas", "recent_spend", "previous_roas", "previous_spend" ], "properties": { "campaign_id": { "type": "string" }, "dr_detected": { "type": "boolean" }, "dr_score": { "type": "integer" }, "dr_threshold_eur": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recent_roas": { "type": "number" }, "recent_spend": { "type": "number" }, "previous_roas": { "type": "number" }, "previous_spend": { "type": "number" } } } }, "sourceConfidence": { "additionalProperties": false, "type": "object", "required": [ "platform_performance", "tracker" ], "properties": { "platform_performance": { "type": "number" }, "tracker": { "type": "number" } } } } }, { "additionalProperties": false, "type": "object", "required": [ "applied", "status" ], "properties": { "applied": { "type": "array", "items": { "type": "object", "allOf": [ { "additionalProperties": false, "type": "object", "required": [ "currentBudgetCents", "entityId", "entityType", "currentSpendCents", "proposedBudgetCents", "score", "reason" ], "properties": { "currentBudgetCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "entityId": { "type": "string" }, "entityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "entityType": { "type": "string" }, "currentSpendCents": { "type": "integer" }, "proposedBudgetCents": { "type": "integer" }, "score": { "type": "number" }, "reason": { "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "accountId": { "type": "string" }, "error": { "type": "string" }, "platform": { "type": "string" }, "proposedBudget": { "type": "number" }, "status": { "anyOf": [ { "type": "string", "enum": [ "applied" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "skipped" ] } ] } } } ] } }, "status": { "anyOf": [ { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } ] } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "423": { "description": "Response 423", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number", "enum": [ 423 ] }, "error": { "type": "string", "enum": [ "Locked" ] }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/allocations": { "get": { "operationId": "getApiV1BudgetPoolsByIdAllocations", "summary": "List budget allocation logs", "tags": [ "budget-pools" ], "description": "Returns recent simulation and execution logs for a budget allocation pool.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "pool_id", "team_id", "user_id", "action_log_id", "mode", "status", "input_snapshot", "allocation_result", "idempotency_key", "campaign_id", "campaign_name", "old_budget_cents", "new_budget_cents", "score", "score_breakdown", "reason", "error_message", "created_at", "executed_at", "allocated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "pool_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "action_log_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string" }, "status": { "type": "string" }, "input_snapshot": { "$comment": "json-value" }, "allocation_result": { "$comment": "json-value" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "old_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "new_budget_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "score_breakdown": { "$comment": "json-value" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "executed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "allocated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/budget-pools/{id}/diminishing-returns": { "get": { "operationId": "getApiV1BudgetPoolsByIdDiminishingReturns", "summary": "Detect diminishing returns", "tags": [ "budget-pools" ], "description": "Analyzes active campaign members in the pool for recent spend growth without ROAS improvement.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "dr_detected", "dr_score", "dr_threshold_eur", "recent_roas", "recent_spend", "previous_roas", "previous_spend" ], "properties": { "campaign_id": { "type": "string" }, "dr_detected": { "type": "boolean" }, "dr_score": { "type": "integer" }, "dr_threshold_eur": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "recent_roas": { "type": "number" }, "recent_spend": { "type": "number" }, "previous_roas": { "type": "number" }, "previous_spend": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/campaigns/bulk-toggle": { "post": { "operationId": "bulkTogglecampaign", "summary": "Bulk toggle campaign statuses", "tags": [ "campaigns" ], "description": "Enqueues a background worker run that sets up to 100 Meta campaign ids to ACTIVE or PAUSED for the specified ad account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "action", "ids" ], "properties": { "account_id": { "minLength": 1, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_run_id", "total" ], "properties": { "worker_run_id": { "format": "uuid", "type": "string" }, "total": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/adsets/bulk-toggle": { "post": { "operationId": "bulkToggleadset", "summary": "Bulk toggle adset statuses", "tags": [ "campaigns" ], "description": "Enqueues a background worker run that sets up to 100 Meta adset ids to ACTIVE or PAUSED for the specified ad account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "action", "ids" ], "properties": { "account_id": { "minLength": 1, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_run_id", "total" ], "properties": { "worker_run_id": { "format": "uuid", "type": "string" }, "total": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/ads/bulk-toggle": { "post": { "operationId": "bulkTogglead", "summary": "Bulk toggle ad statuses", "tags": [ "campaigns" ], "description": "Enqueues a background worker run that sets up to 100 Meta ad ids to ACTIVE or PAUSED for the specified ad account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "account_id", "action", "ids" ], "properties": { "account_id": { "minLength": 1, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_run_id", "total" ], "properties": { "worker_run_id": { "format": "uuid", "type": "string" }, "total": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/gather": { "post": { "operationId": "postApiV1CampaignContextGather", "summary": "Gather an AI-native campaign context snapshot", "tags": [ "campaign-context" ], "description": "Collects platform, tracker, commerce, business, competitor, market, and landing-page context into a draft snapshot.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ad_account_id": { "maxLength": 100, "type": "string" }, "brief_input": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "from_date": { "format": "date", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/{briefId}/gather-context": { "post": { "operationId": "postApiV1CampaignContextByBriefIdGatherContext", "summary": "Gather a campaign context snapshot for a completed brief", "tags": [ "campaign-context" ], "description": "Builds campaign context from a completed briefing canvas and optional request overrides.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ad_account_id": { "maxLength": 100, "type": "string" }, "brief_input": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "from_date": { "format": "date", "type": "string" }, "project_id": { "format": "uuid", "type": "string" }, "to_date": { "format": "date", "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } }, { "type": "null" } ] } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/{briefId}/snapshot": { "get": { "operationId": "getApiV1CampaignContextByBriefIdSnapshot", "summary": "Get latest campaign context snapshot for a brief", "tags": [ "campaign-context" ], "description": "Returns the most recent campaign context snapshot associated with a completed brief.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/{briefId}/snapshot/sources": { "get": { "operationId": "getApiV1CampaignContextByBriefIdSnapshotSources", "summary": "Get source status for the latest campaign context snapshot", "tags": [ "campaign-context" ], "description": "Returns source coverage, missing-source reasons, brief gaps, and confidence for the latest brief snapshot.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "status", "confidence_score", "sources_used", "sources_missing", "brief_gaps" ], "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/{briefId}/snapshot/approve": { "patch": { "operationId": "patchApiV1CampaignContextByBriefIdSnapshotApprove", "summary": "Approve latest context snapshot for a completed brief", "tags": [ "campaign-context" ], "description": "Approves the latest draft snapshot for a completed brief and mirrors it into approved AI context.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "briefId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/snapshots/{id}": { "get": { "operationId": "getApiV1CampaignContextSnapshotsById", "summary": "Get campaign context snapshot", "tags": [ "campaign-context" ], "description": "Returns a campaign context snapshot by id within the accessible team scope.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1CampaignContextSnapshotsById", "summary": "Patch editable context snapshot fields before approval", "tags": [ "campaign-context" ], "description": "Updates editable JSON sections on a draft campaign context snapshot before approval.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "brief_input": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "platform_performance": { "$comment": "json-value" }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "tracker_attribution": { "$comment": "json-value" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-context/snapshots/{id}/approve": { "post": { "operationId": "postApiV1CampaignContextSnapshotsByIdApprove", "summary": "Approve a context snapshot and freeze it for downstream AI modules", "tags": [ "campaign-context" ], "description": "Marks a campaign context snapshot as approved and mirrors it into downstream AI context.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "user_id", "brief_id", "project_id", "ad_account_id", "brief_input", "status", "platform_performance", "tracker_attribution", "ecommerce_data", "business_context", "competitor_intelligence", "market_research", "landing_page_analysis", "sources_used", "sources_missing", "brief_gaps", "confidence_score", "gathering_duration_ms", "approved_at", "approved_by", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "brief_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brief_input": { "$comment": "json-value" }, "status": { "anyOf": [ { "type": "string", "enum": [ "gathering" ] }, { "type": "string", "enum": [ "draft" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "platform_performance": { "$comment": "json-value" }, "tracker_attribution": { "$comment": "json-value" }, "ecommerce_data": { "$comment": "json-value" }, "business_context": { "$comment": "json-value" }, "competitor_intelligence": { "$comment": "json-value" }, "market_research": { "$comment": "json-value" }, "landing_page_analysis": { "$comment": "json-value" }, "sources_used": { "type": "array", "items": { "$comment": "json-value" } }, "sources_missing": { "type": "array", "items": { "$comment": "json-value" } }, "brief_gaps": { "type": "array", "items": { "$comment": "json-value" } }, "confidence_score": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "gathering_duration_ms": { "type": "integer" }, "approved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "approved_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "edited_before_approval": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/campaign-drafts": { "get": { "operationId": "listCampaignDrafts", "summary": "List campaign drafts", "tags": [ "campaigns" ], "description": "Returns a paginated list of campaign drafts for the authenticated user, with optional status filtering.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "account_id", "name", "source", "status", "platform", "current_step", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "type": "string" }, "current_step": { "type": "integer" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "title": "PublicCampaignDraftResponse" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } }, "post": { "operationId": "createCampaignDraft", "summary": "Create a campaign draft", "tags": [ "campaigns" ], "description": "Creates a new campaign draft with the given name, ad account, and canonical campaign structure.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "account_id": { "type": "string" }, "canonical_campaign": { "additionalProperties": false, "description": "Canonical campaign JSONB shape used by campaign drafts. Fields are optional because drafts are auto-saved while incomplete.", "type": "object", "properties": { "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adSets": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "ads": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "advantageCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "callToAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyAiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "creativeFormat": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SINGLE_IMAGE" ] }, { "type": "string", "enum": [ "SINGLE_VIDEO" ] }, { "type": "string", "enum": [ "CAROUSEL" ] }, { "type": "string", "enum": [ "EXISTING_POST" ] }, { "type": "string", "enum": [ "CATALOG" ] }, { "type": "string", "enum": [ "FLEXIBLE" ] } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "dynamicCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "existingPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "existingPostPreview": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleDescriptions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleDisplayPath1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleDisplayPath2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleLogoAsset": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleYoutubeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headlineVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "multiAdvertiser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "multilanguage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placementAssets": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "feed": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "story": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "placementCustomization": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryTextVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryMedia": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "secondaryPrimaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdDisclaimer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdFavoriting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatAdType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAppIconMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatBrandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatDeepLinkUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMessageText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPhoneNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatShareable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatSmartPrefetching": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaCta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "targetLanguage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unmatchedAudienceVideo": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "safe" ] }, { "type": "string", "enum": [ "targeted" ] } ] }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urlParameters": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "attribution": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "clickWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] } ] }, { "type": "null" } ] }, "viewWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] } ] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "bidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "billingEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "customAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "destinationType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dsaFields": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "beneficiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excludedAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optimizationGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placements": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "audienceNetworkPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "facebookPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "instagramPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "messengerPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "publisherPlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "facebook" ] }, { "type": "string", "enum": [ "instagram" ] }, { "type": "string", "enum": [ "audience_network" ] }, { "type": "string", "enum": [ "messenger" ] }, { "type": "string", "enum": [ "threads" ] } ] } }, { "type": "null" } ] }, "snapchatBrandSuitability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConfig": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatCustomType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "threadsPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promotedObject": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customEventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectStoreUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "roasFloor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAudienceType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "PROSPECTING" ] }, { "type": "string", "enum": [ "RETARGETING" ] } ] }, { "type": "null" } ] }, "snapchatCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConversionLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatProductSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spendPercent": { "anyOf": [ { "minimum": 1, "maximum": 100, "type": "number" }, { "type": "null" } ] }, "startDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "targeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "advantageAge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageAudience": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageDetailedTargeting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageGender": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageLookalike": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ageMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ageMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "devicePlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "mobile" ] }, { "type": "string", "enum": [ "desktop" ] } ] } }, { "type": "null" } ] }, "genders": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locales": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locations": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "countryCode", "key", "name", "type" ], "properties": { "countryCode": { "type": "string" }, "distanceUnit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "anyOf": [ { "minimum": 10, "maximum": 80, "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "region" ] }, { "type": "string", "enum": [ "city" ] } ] } } } }, { "type": "null" } ] }, "operatingSystems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "campaign": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "acceleratedDelivery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantagePlus": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bidStrategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetLevel": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CBO" ] }, { "type": "string", "enum": [ "ABO" ] } ] }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "buyingType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "AUCTION" ] }, { "type": "string", "enum": [ "RESERVED" ] } ] }, { "type": "null" } ] }, "customerAcquisition": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "googleGoal": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SALES" ] }, { "type": "string", "enum": [ "LEADS" ] }, { "type": "string", "enum": [ "WEBSITE_TRAFFIC" ] }, { "type": "string", "enum": [ "APP_PROMOTION" ] }, { "type": "string", "enum": [ "AWARENESS" ] }, { "type": "string", "enum": [ "LOCAL_STORE" ] }, { "type": "string", "enum": [ "NO_GOAL" ] } ] }, { "type": "null" } ] }, "googleMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainBudgetPacing": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "outbrainConversionGoalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainCpcCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainDailyBudgetCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainDayparting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "FRIDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "MONDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SATURDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SUNDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "THURSDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "TUESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "WEDNESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "outbrainEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainTargeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "browsers": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "custom_audiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "iab_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "operating_systems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sections": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "include": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "reachGoals": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "phoneCall": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "storeVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "websiteVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatDynamicAds": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatLifetimeSpendCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatMobileApp": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "android_app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ios_app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatPromotionType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "APP_INSTALL" ] }, { "type": "string", "enum": [ "APP_REENGAGEMENT" ] } ] }, { "type": "null" } ] }, "snapchatPublicProfileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "specialAdCategories": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "NONE" ] }, { "type": "string", "enum": [ "HOUSING" ] }, { "type": "string", "enum": [ "EMPLOYMENT" ] }, { "type": "string", "enum": [ "CREDIT" ] }, { "type": "string", "enum": [ "ISSUES_ELECTIONS_POLITICS" ] }, { "type": "string", "enum": [ "ONLINE_GAMBLING_AND_GAMING" ] } ] } }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaBidStrategy": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "FIXED" ] }, { "type": "string", "enum": [ "TARGET_CPA" ] } ] }, { "type": "null" } ] }, "taboolaBrandingText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaCpaGoal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaCpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaDailyCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaPricingModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaSpendingLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaSpendingLimitType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "tiktokAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokBidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tiktokBidType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "BID_TYPE_CUSTOM" ] }, { "type": "string", "enum": [ "BID_TYPE_NO_BID" ] } ] }, { "type": "null" } ] }, "tiktokBillingEvent": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CPM" ] }, { "type": "string", "enum": [ "OCPM" ] }, { "type": "string", "enum": [ "CPC" ] }, { "type": "string", "enum": [ "CPV" ] } ] }, { "type": "null" } ] }, "tiktokCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "TT_USER" ] }, { "type": "string", "enum": [ "CUSTOMIZED_USER" ] }, { "type": "string", "enum": [ "BC_AUTH_TT" ] } ] }, { "type": "null" } ] }, "tiktokItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokOptimizeGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokRoasBid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "editWarning": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "learning_reset" ] }, { "type": "string", "enum": [ "recreate" ] }, { "type": "string", "enum": [ "re_review" ] }, { "type": "string", "enum": [ "id_change" ] } ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "create_all" ] }, { "type": "string", "enum": [ "ads_only" ] }, { "type": "string", "enum": [ "add_adset" ] } ] }, { "type": "null" } ] }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "current_step": { "minimum": 0, "maximum": 20, "type": "integer" }, "platform": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "account_id", "name", "source", "status", "platform", "current_step", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "type": "string" }, "current_step": { "type": "integer" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}": { "get": { "operationId": "getCampaignDraft", "summary": "Get campaign draft by ID", "tags": [ "campaigns" ], "description": "Retrieves a single campaign draft by its UUID.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "account_id", "name", "source", "status", "platform", "current_step", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "type": "string" }, "current_step": { "type": "integer" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } }, "patch": { "operationId": "updateCampaignDraft", "summary": "Update campaign draft (auto-save with deep merge)", "tags": [ "campaigns" ], "description": "Partially updates a campaign draft using deep merge, enabling auto-save of individual fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "account_id": { "type": "string" }, "canonical_campaign": { "additionalProperties": false, "description": "Canonical campaign JSONB shape used by campaign drafts. Fields are optional because drafts are auto-saved while incomplete.", "type": "object", "properties": { "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adSets": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "ads": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "advantageCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "callToAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyAiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "creativeFormat": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SINGLE_IMAGE" ] }, { "type": "string", "enum": [ "SINGLE_VIDEO" ] }, { "type": "string", "enum": [ "CAROUSEL" ] }, { "type": "string", "enum": [ "EXISTING_POST" ] }, { "type": "string", "enum": [ "CATALOG" ] }, { "type": "string", "enum": [ "FLEXIBLE" ] } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "dynamicCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "existingPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "existingPostPreview": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleDescriptions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleDisplayPath1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleDisplayPath2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleLogoAsset": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleYoutubeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headlineVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "multiAdvertiser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "multilanguage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placementAssets": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "feed": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "story": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "placementCustomization": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryTextVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryMedia": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "secondaryPrimaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdDisclaimer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdFavoriting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatAdType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAppIconMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatBrandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatDeepLinkUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMessageText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPhoneNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatShareable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatSmartPrefetching": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaCta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "targetLanguage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unmatchedAudienceVideo": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "safe" ] }, { "type": "string", "enum": [ "targeted" ] } ] }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urlParameters": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "attribution": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "clickWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] } ] }, { "type": "null" } ] }, "viewWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] } ] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "bidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "billingEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "customAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "destinationType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dsaFields": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "beneficiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excludedAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optimizationGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placements": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "audienceNetworkPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "facebookPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "instagramPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "messengerPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "publisherPlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "facebook" ] }, { "type": "string", "enum": [ "instagram" ] }, { "type": "string", "enum": [ "audience_network" ] }, { "type": "string", "enum": [ "messenger" ] }, { "type": "string", "enum": [ "threads" ] } ] } }, { "type": "null" } ] }, "snapchatBrandSuitability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConfig": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatCustomType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "threadsPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promotedObject": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customEventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectStoreUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "roasFloor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAudienceType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "PROSPECTING" ] }, { "type": "string", "enum": [ "RETARGETING" ] } ] }, { "type": "null" } ] }, "snapchatCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConversionLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatProductSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spendPercent": { "anyOf": [ { "minimum": 1, "maximum": 100, "type": "number" }, { "type": "null" } ] }, "startDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "targeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "advantageAge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageAudience": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageDetailedTargeting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageGender": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageLookalike": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ageMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ageMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "devicePlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "mobile" ] }, { "type": "string", "enum": [ "desktop" ] } ] } }, { "type": "null" } ] }, "genders": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locales": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locations": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "countryCode", "key", "name", "type" ], "properties": { "countryCode": { "type": "string" }, "distanceUnit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "anyOf": [ { "minimum": 10, "maximum": 80, "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "region" ] }, { "type": "string", "enum": [ "city" ] } ] } } } }, { "type": "null" } ] }, "operatingSystems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "campaign": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "acceleratedDelivery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantagePlus": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bidStrategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetLevel": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CBO" ] }, { "type": "string", "enum": [ "ABO" ] } ] }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "buyingType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "AUCTION" ] }, { "type": "string", "enum": [ "RESERVED" ] } ] }, { "type": "null" } ] }, "customerAcquisition": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "googleGoal": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SALES" ] }, { "type": "string", "enum": [ "LEADS" ] }, { "type": "string", "enum": [ "WEBSITE_TRAFFIC" ] }, { "type": "string", "enum": [ "APP_PROMOTION" ] }, { "type": "string", "enum": [ "AWARENESS" ] }, { "type": "string", "enum": [ "LOCAL_STORE" ] }, { "type": "string", "enum": [ "NO_GOAL" ] } ] }, { "type": "null" } ] }, "googleMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainBudgetPacing": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "outbrainConversionGoalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainCpcCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainDailyBudgetCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainDayparting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "FRIDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "MONDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SATURDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SUNDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "THURSDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "TUESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "WEDNESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "outbrainEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainTargeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "browsers": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "custom_audiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "iab_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "operating_systems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sections": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "include": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "reachGoals": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "phoneCall": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "storeVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "websiteVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatDynamicAds": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatLifetimeSpendCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatMobileApp": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "android_app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ios_app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatPromotionType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "APP_INSTALL" ] }, { "type": "string", "enum": [ "APP_REENGAGEMENT" ] } ] }, { "type": "null" } ] }, "snapchatPublicProfileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "specialAdCategories": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "NONE" ] }, { "type": "string", "enum": [ "HOUSING" ] }, { "type": "string", "enum": [ "EMPLOYMENT" ] }, { "type": "string", "enum": [ "CREDIT" ] }, { "type": "string", "enum": [ "ISSUES_ELECTIONS_POLITICS" ] }, { "type": "string", "enum": [ "ONLINE_GAMBLING_AND_GAMING" ] } ] } }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaBidStrategy": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "FIXED" ] }, { "type": "string", "enum": [ "TARGET_CPA" ] } ] }, { "type": "null" } ] }, "taboolaBrandingText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaCpaGoal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaCpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaDailyCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaPricingModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaSpendingLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaSpendingLimitType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "tiktokAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokBidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tiktokBidType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "BID_TYPE_CUSTOM" ] }, { "type": "string", "enum": [ "BID_TYPE_NO_BID" ] } ] }, { "type": "null" } ] }, "tiktokBillingEvent": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CPM" ] }, { "type": "string", "enum": [ "OCPM" ] }, { "type": "string", "enum": [ "CPC" ] }, { "type": "string", "enum": [ "CPV" ] } ] }, { "type": "null" } ] }, "tiktokCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "TT_USER" ] }, { "type": "string", "enum": [ "CUSTOMIZED_USER" ] }, { "type": "string", "enum": [ "BC_AUTH_TT" ] } ] }, { "type": "null" } ] }, "tiktokItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokOptimizeGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokRoasBid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "editWarning": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "learning_reset" ] }, { "type": "string", "enum": [ "recreate" ] }, { "type": "string", "enum": [ "re_review" ] }, { "type": "string", "enum": [ "id_change" ] } ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "create_all" ] }, { "type": "string", "enum": [ "ads_only" ] }, { "type": "string", "enum": [ "add_adset" ] } ] }, { "type": "null" } ] }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "current_step": { "minimum": 0, "maximum": 20, "type": "integer" }, "status": { "type": "string" }, "platform": { "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "account_id", "name", "source", "status", "platform", "current_step", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "type": "string" }, "current_step": { "type": "integer" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } }, "delete": { "operationId": "deleteCampaignDraft", "summary": "Delete campaign draft", "tags": [ "campaigns" ], "description": "Soft-deletes a campaign draft by its UUID.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/validate": { "post": { "operationId": "validateCampaignDraft", "summary": "Validate campaign draft", "tags": [ "campaigns" ], "description": "Runs full validation on all fields of a campaign draft and returns any errors or warnings. Optionally accepts canonical_campaign in body to validate in-memory state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "canonical_campaign": { "additionalProperties": false, "description": "Canonical campaign JSONB shape used by campaign drafts. Fields are optional because drafts are auto-saved while incomplete.", "type": "object", "properties": { "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adSets": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "ads": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "advantageCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "callToAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyAiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "creativeFormat": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SINGLE_IMAGE" ] }, { "type": "string", "enum": [ "SINGLE_VIDEO" ] }, { "type": "string", "enum": [ "CAROUSEL" ] }, { "type": "string", "enum": [ "EXISTING_POST" ] }, { "type": "string", "enum": [ "CATALOG" ] }, { "type": "string", "enum": [ "FLEXIBLE" ] } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "dynamicCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "existingPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "existingPostPreview": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleDescriptions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleDisplayPath1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleDisplayPath2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleLogoAsset": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleYoutubeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headlineVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "multiAdvertiser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "multilanguage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placementAssets": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "feed": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "story": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "placementCustomization": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryTextVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryMedia": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "secondaryPrimaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdDisclaimer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdFavoriting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatAdType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAppIconMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatBrandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatDeepLinkUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMessageText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPhoneNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatShareable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatSmartPrefetching": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaCta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "targetLanguage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unmatchedAudienceVideo": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "safe" ] }, { "type": "string", "enum": [ "targeted" ] } ] }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urlParameters": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "attribution": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "clickWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] } ] }, { "type": "null" } ] }, "viewWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] } ] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "bidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "billingEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "customAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "destinationType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dsaFields": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "beneficiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excludedAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optimizationGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placements": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "audienceNetworkPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "facebookPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "instagramPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "messengerPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "publisherPlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "facebook" ] }, { "type": "string", "enum": [ "instagram" ] }, { "type": "string", "enum": [ "audience_network" ] }, { "type": "string", "enum": [ "messenger" ] }, { "type": "string", "enum": [ "threads" ] } ] } }, { "type": "null" } ] }, "snapchatBrandSuitability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConfig": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatCustomType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "threadsPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promotedObject": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customEventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectStoreUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "roasFloor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAudienceType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "PROSPECTING" ] }, { "type": "string", "enum": [ "RETARGETING" ] } ] }, { "type": "null" } ] }, "snapchatCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConversionLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatProductSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spendPercent": { "anyOf": [ { "minimum": 1, "maximum": 100, "type": "number" }, { "type": "null" } ] }, "startDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "targeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "advantageAge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageAudience": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageDetailedTargeting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageGender": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageLookalike": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ageMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ageMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "devicePlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "mobile" ] }, { "type": "string", "enum": [ "desktop" ] } ] } }, { "type": "null" } ] }, "genders": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locales": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locations": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "countryCode", "key", "name", "type" ], "properties": { "countryCode": { "type": "string" }, "distanceUnit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "anyOf": [ { "minimum": 10, "maximum": 80, "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "region" ] }, { "type": "string", "enum": [ "city" ] } ] } } } }, { "type": "null" } ] }, "operatingSystems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "campaign": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "acceleratedDelivery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantagePlus": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bidStrategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetLevel": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CBO" ] }, { "type": "string", "enum": [ "ABO" ] } ] }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "buyingType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "AUCTION" ] }, { "type": "string", "enum": [ "RESERVED" ] } ] }, { "type": "null" } ] }, "customerAcquisition": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "googleGoal": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SALES" ] }, { "type": "string", "enum": [ "LEADS" ] }, { "type": "string", "enum": [ "WEBSITE_TRAFFIC" ] }, { "type": "string", "enum": [ "APP_PROMOTION" ] }, { "type": "string", "enum": [ "AWARENESS" ] }, { "type": "string", "enum": [ "LOCAL_STORE" ] }, { "type": "string", "enum": [ "NO_GOAL" ] } ] }, { "type": "null" } ] }, "googleMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainBudgetPacing": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "outbrainConversionGoalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainCpcCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainDailyBudgetCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainDayparting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "FRIDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "MONDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SATURDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SUNDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "THURSDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "TUESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "WEDNESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "outbrainEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainTargeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "browsers": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "custom_audiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "iab_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "operating_systems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sections": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "include": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "reachGoals": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "phoneCall": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "storeVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "websiteVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatDynamicAds": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatLifetimeSpendCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatMobileApp": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "android_app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ios_app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatPromotionType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "APP_INSTALL" ] }, { "type": "string", "enum": [ "APP_REENGAGEMENT" ] } ] }, { "type": "null" } ] }, "snapchatPublicProfileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "specialAdCategories": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "NONE" ] }, { "type": "string", "enum": [ "HOUSING" ] }, { "type": "string", "enum": [ "EMPLOYMENT" ] }, { "type": "string", "enum": [ "CREDIT" ] }, { "type": "string", "enum": [ "ISSUES_ELECTIONS_POLITICS" ] }, { "type": "string", "enum": [ "ONLINE_GAMBLING_AND_GAMING" ] } ] } }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaBidStrategy": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "FIXED" ] }, { "type": "string", "enum": [ "TARGET_CPA" ] } ] }, { "type": "null" } ] }, "taboolaBrandingText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaCpaGoal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaCpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaDailyCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaPricingModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaSpendingLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaSpendingLimitType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "tiktokAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokBidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tiktokBidType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "BID_TYPE_CUSTOM" ] }, { "type": "string", "enum": [ "BID_TYPE_NO_BID" ] } ] }, { "type": "null" } ] }, "tiktokBillingEvent": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CPM" ] }, { "type": "string", "enum": [ "OCPM" ] }, { "type": "string", "enum": [ "CPC" ] }, { "type": "string", "enum": [ "CPV" ] } ] }, { "type": "null" } ] }, "tiktokCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "TT_USER" ] }, { "type": "string", "enum": [ "CUSTOMIZED_USER" ] }, { "type": "string", "enum": [ "BC_AUTH_TT" ] } ] }, { "type": "null" } ] }, "tiktokItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokOptimizeGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokRoasBid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "editWarning": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "learning_reset" ] }, { "type": "string", "enum": [ "recreate" ] }, { "type": "string", "enum": [ "re_review" ] }, { "type": "string", "enum": [ "id_change" ] } ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "create_all" ] }, { "type": "string", "enum": [ "ads_only" ] }, { "type": "string", "enum": [ "add_adset" ] } ] }, { "type": "null" } ] }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "platform": { "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/validate-field": { "post": { "operationId": "validateCampaignDraftField", "summary": "Validate a single field in campaign draft", "tags": [ "campaigns" ], "description": "Validates a specific field path in the campaign draft and returns its validation result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "field_path" ], "properties": { "field_path": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/preflight": { "post": { "operationId": "preflightCampaignDraft", "summary": "Pre-flight check: verify account, tokens, and platform resources", "tags": [ "campaigns" ], "description": "Verifies that the platform account, tokens, and required native resources referenced in the draft are valid and accessible before publishing.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/dry-run": { "post": { "operationId": "dryRunCampaignDraft", "summary": "Dry run: preview native API payloads", "tags": [ "campaigns" ], "description": "Generates the native platform API payloads that would be sent on publish, without actually creating anything. Returns validation result and preview payloads.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "validation" ], "properties": { "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "preview": { "additionalProperties": true, "type": "object", "required": [ "campaign", "adSets" ], "properties": { "campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "adSets": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "adSet", "ads" ], "properties": { "adSet": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "ads": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "validation" ], "properties": { "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "preview": { "additionalProperties": true, "type": "object", "required": [ "campaign", "adSets" ], "properties": { "campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "adSets": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "adSet", "ads" ], "properties": { "adSet": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "ads": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/publish": { "post": { "operationId": "publishCampaignDraft", "summary": "Publish campaign draft via native worker", "tags": [ "campaigns" ], "description": "Publishes the campaign draft to its selected platform by dispatching it to the native publish worker. Requires an active subscription.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "idempotency_key": { "maxLength": 255, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "publishJobId" ], "properties": { "publishJobId": { "type": "string" }, "naming_warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/multi-publish": { "post": { "operationId": "multiPublishCampaignDraft", "summary": "Publish campaign draft to multiple ad accounts", "tags": [ "campaigns" ], "description": "Publishes the same campaign draft to multiple target ad accounts on the draft platform. Creates one publish job per target account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "targets" ], "properties": { "targets": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "account_id", "fan_page_id" ], "properties": { "account_id": { "minLength": 1, "type": "string" }, "fan_page_id": { "minLength": 1, "type": "string" }, "pixel_id": { "type": "string" } } } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "publishJobs" ], "properties": { "publishJobs": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "publishJobId", "accountId" ], "properties": { "publishJobId": { "type": "string" }, "accountId": { "type": "string" } } } }, "naming_warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "description": "Reason the operation was rejected (e.g. \"Draft not found\", \"Validation failed\", \"Duplicate account_id in targets\").", "type": "string" }, "validation": { "additionalProperties": true, "type": "object", "required": [ "valid", "errors", "warnings", "info" ], "properties": { "valid": { "type": "boolean" }, "errors": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "warnings": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } }, "info": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "code", "fieldPath", "message", "severity" ], "properties": { "code": { "description": "Stable error code (e.g. \"INVALID_AGE_RANGE\").", "type": "string" }, "fieldPath": { "description": "Dot-notation path of the offending field.", "type": "string" }, "message": { "type": "string" }, "metaErrorCode": { "type": "number" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "error" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "info" ] } ] } } } } } }, "code": { "description": "Machine-readable code (e.g. NAMING_CONVENTION_BLOCKED).", "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/publish-jobs/{jobId}": { "get": { "operationId": "getCampaignPublishJob", "summary": "Get publish job status with logs", "tags": [ "campaigns" ], "description": "Returns the current status and execution logs of a specific publish job.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "jobId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "campaign_draft_id", "source", "status", "platform", "canonical_campaign", "total_entities", "completed_entities", "failed_entities", "dry_run", "idempotency_key", "created_at", "processing_started_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "campaign_draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "total_entities": { "type": "integer" }, "completed_entities": { "type": "integer" }, "failed_entities": { "type": "integer" }, "dry_run": { "type": "boolean" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "processing_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "logs": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "publish_job_id", "entity_type", "entity_name", "status", "attempt", "error_message", "meta_entity_id", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "publish_job_id": { "format": "uuid", "type": "string" }, "entity_type": { "type": "string" }, "entity_name": { "type": "string" }, "status": { "type": "string" }, "attempt": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meta_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } }, "title": "PublicPublishLogResponse" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/publish-jobs": { "get": { "operationId": "listCampaignPublishJobs", "summary": "List publish jobs for a campaign draft", "tags": [ "campaigns" ], "description": "Returns all publish jobs associated with a specific campaign draft.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "campaign_draft_id", "source", "status", "platform", "canonical_campaign", "total_entities", "completed_entities", "failed_entities", "dry_run", "idempotency_key", "created_at", "processing_started_at", "completed_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "campaign_draft_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "total_entities": { "type": "integer" }, "completed_entities": { "type": "integer" }, "failed_entities": { "type": "integer" }, "dry_run": { "type": "boolean" }, "idempotency_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "processing_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "logs": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "publish_job_id", "entity_type", "entity_name", "status", "attempt", "error_message", "meta_entity_id", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "publish_job_id": { "format": "uuid", "type": "string" }, "entity_type": { "type": "string" }, "entity_name": { "type": "string" }, "status": { "type": "string" }, "attempt": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meta_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } }, "title": "PublicPublishJobResponse" } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/{id}/save-template": { "post": { "operationId": "saveCampaignDraftAsTemplate", "summary": "Save campaign draft as template", "tags": [ "campaigns" ], "description": "Saves the current state of a campaign draft as a reusable template.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "source", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaign-drafts/from-template": { "post": { "operationId": "createCampaignDraftFromTemplate", "summary": "Create campaign draft from template", "tags": [ "campaigns" ], "description": "Creates a new campaign draft pre-populated with the canonical campaign structure from an existing template.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "template_id", "name" ], "properties": { "template_id": { "format": "uuid", "type": "string" }, "name": { "minLength": 1, "maxLength": 500, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "account_id", "name", "source", "status", "platform", "current_step", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "platform": { "type": "string" }, "current_step": { "type": "integer" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "error_code": { "type": "string" }, "detail": {} } } } } } } } }, "/api/v1/campaigns/{campaignId}/name": { "patch": { "operationId": "renameCampaign", "summary": "Rename a campaign in-place", "tags": [ "campaigns" ], "description": "Updates only the `name` field of a Meta campaign (Graph API POST /). Intended for the Ads Manager list quick-rename affordance — campaign structure is untouched, so the call is safe to wire to optimistic updates on the frontend.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "account_id" ], "properties": { "name": { "minLength": 1, "maxLength": 400, "type": "string" }, "account_id": { "minLength": 1, "type": "string" }, "platform": { "type": "string", "enum": [ "meta" ] } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "campaignId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "name" ], "properties": { "campaign_id": { "type": "string" }, "name": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/campaign-templates": { "get": { "operationId": "listCampaignTemplates", "summary": "List campaign templates", "tags": [ "campaigns" ], "description": "Returns all campaign templates accessible to the authenticated user.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "source", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "title": "PublicCampaignTemplateResponse" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "createCampaignTemplate", "summary": "Create a campaign template", "tags": [ "campaigns" ], "description": "Creates a new campaign template with the given name and canonical campaign structure.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "draft_id": { "format": "uuid", "type": "string" }, "canonical_campaign": { "additionalProperties": false, "description": "Canonical campaign JSONB shape used by campaign drafts. Fields are optional because drafts are auto-saved while incomplete.", "type": "object", "properties": { "accountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adSets": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "ads": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "advantageCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "callToAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyAiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "creativeFormat": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SINGLE_IMAGE" ] }, { "type": "string", "enum": [ "SINGLE_VIDEO" ] }, { "type": "string", "enum": [ "CAROUSEL" ] }, { "type": "string", "enum": [ "EXISTING_POST" ] }, { "type": "string", "enum": [ "CATALOG" ] }, { "type": "string", "enum": [ "FLEXIBLE" ] } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptionVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "dynamicCreative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "existingPostId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "existingPostPreview": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleDescriptions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleDisplayPath1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleDisplayPath2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "googleHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "googleLogoAsset": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "googleYoutubeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headlineVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "multiAdvertiser": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "multilanguage": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placementAssets": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "feed": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "story": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "placementCustomization": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryTextVariations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "secondaryMedia": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "aiGenerated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cardDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cardHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crops": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "100x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "191x100": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "400x500": { "anyOf": [ { "minItems": 2, "maxItems": 2, "type": "array", "items": { "minItems": 2, "maxItems": 2, "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fileSizeBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metaHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, { "type": "null" } ] }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "secondaryPrimaryText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondaryUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdDisclaimer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAdFavoriting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatAdType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAppIconMediaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatBrandName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatDeepLinkUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatMessageText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPhoneNumberId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatShareable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatSmartPrefetching": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaCta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaHeadlines": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "targetLanguage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unmatchedAudienceVideo": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "safe" ] }, { "type": "string", "enum": [ "targeted" ] } ] }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urlParameters": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "attribution": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "clickWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] } ] }, { "type": "null" } ] }, "viewWindow": { "anyOf": [ { "anyOf": [ { "type": "number", "enum": [ 0 ] }, { "type": "number", "enum": [ 1 ] } ] }, { "type": "null" } ] } } }, { "type": "null" } ] }, "bidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "billingEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "customAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "destinationType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dsaFields": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "beneficiary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excludedAudiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "optimizationGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placements": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "audienceNetworkPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "automatic": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "facebookPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "instagramPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "messengerPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "publisherPlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "facebook" ] }, { "type": "string", "enum": [ "instagram" ] }, { "type": "string", "enum": [ "audience_network" ] }, { "type": "string", "enum": [ "messenger" ] }, { "type": "string", "enum": [ "threads" ] } ] } }, { "type": "null" } ] }, "snapchatBrandSuitability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConfig": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatCustomType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "threadsPositions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promotedObject": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customEventType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objectStoreUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "roasFloor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatAudienceType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "PROSPECTING" ] }, { "type": "string", "enum": [ "RETARGETING" ] } ] }, { "type": "null" } ] }, "snapchatCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatConversionLocation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snapchatProductSetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spendPercent": { "anyOf": [ { "minimum": 1, "maximum": 100, "type": "number" }, { "type": "null" } ] }, "startDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "targeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "advantageAge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageAudience": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageDetailedTargeting": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageGender": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantageLookalike": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ageMax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ageMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "devicePlatforms": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "mobile" ] }, { "type": "string", "enum": [ "desktop" ] } ] } }, { "type": "null" } ] }, "genders": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locales": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "locations": { "anyOf": [ { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "countryCode", "key", "name", "type" ], "properties": { "countryCode": { "type": "string" }, "distanceUnit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "name": { "type": "string" }, "radius": { "anyOf": [ { "minimum": 10, "maximum": 80, "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "region" ] }, { "type": "string", "enum": [ "city" ] } ] } } } }, { "type": "null" } ] }, "operatingSystems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } } }, { "type": "null" } ] }, "campaign": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "acceleratedDelivery": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "advantagePlus": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bidStrategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetLevel": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CBO" ] }, { "type": "string", "enum": [ "ABO" ] } ] }, { "type": "null" } ] }, "budgetType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "LIFETIME" ] } ] }, { "type": "null" } ] }, "buyingType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "AUCTION" ] }, { "type": "string", "enum": [ "RESERVED" ] } ] }, { "type": "null" } ] }, "customerAcquisition": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "googleGoal": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "SALES" ] }, { "type": "string", "enum": [ "LEADS" ] }, { "type": "string", "enum": [ "WEBSITE_TRAFFIC" ] }, { "type": "string", "enum": [ "APP_PROMOTION" ] }, { "type": "string", "enum": [ "AWARENESS" ] }, { "type": "string", "enum": [ "LOCAL_STORE" ] }, { "type": "string", "enum": [ "NO_GOAL" ] } ] }, { "type": "null" } ] }, "googleMerchantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTokenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainBudgetPacing": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "outbrainConversionGoalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainCpcCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainDailyBudgetCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "outbrainDayparting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "FRIDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "MONDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SATURDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "SUNDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "THURSDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "TUESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] }, "WEDNESDAY": { "anyOf": [ { "type": "array", "items": { "minimum": 0, "maximum": 23, "type": "integer" } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "outbrainEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outbrainTargeting": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "browsers": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "countries": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "custom_audiences": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "iab_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "operating_systems": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sections": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "include": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "reachGoals": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "phoneCall": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "storeVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "websiteVisit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatDynamicAds": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "snapchatLifetimeSpendCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snapchatMobileApp": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "android_app_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ios_app_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "snapchatPromotionType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "APP_INSTALL" ] }, { "type": "string", "enum": [ "APP_REENGAGEMENT" ] } ] }, { "type": "null" } ] }, "snapchatPublicProfileId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "specialAdCategories": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "NONE" ] }, { "type": "string", "enum": [ "HOUSING" ] }, { "type": "string", "enum": [ "EMPLOYMENT" ] }, { "type": "string", "enum": [ "CREDIT" ] }, { "type": "string", "enum": [ "ISSUES_ELECTIONS_POLITICS" ] }, { "type": "string", "enum": [ "ONLINE_GAMBLING_AND_GAMING" ] } ] } }, { "type": "null" } ] }, "status": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, { "type": "null" } ] }, "taboolaBidStrategy": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "FIXED" ] }, { "type": "string", "enum": [ "TARGET_CPA" ] } ] }, { "type": "null" } ] }, "taboolaBrandingText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaCpaGoal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaCpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaDailyCap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaPricingModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taboolaSpendingLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "taboolaSpendingLimitType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "MONTHLY" ] }, { "type": "string", "enum": [ "ENTIRE" ] } ] }, { "type": "null" } ] }, "tiktokAppId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokBidAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tiktokBidType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "BID_TYPE_CUSTOM" ] }, { "type": "string", "enum": [ "BID_TYPE_NO_BID" ] } ] }, { "type": "null" } ] }, "tiktokBillingEvent": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "CPM" ] }, { "type": "string", "enum": [ "OCPM" ] }, { "type": "string", "enum": [ "CPC" ] }, { "type": "string", "enum": [ "CPV" ] } ] }, { "type": "null" } ] }, "tiktokCatalogId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokIdentityType": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "TT_USER" ] }, { "type": "string", "enum": [ "CUSTOMIZED_USER" ] }, { "type": "string", "enum": [ "BC_AUTH_TT" ] } ] }, { "type": "null" } ] }, "tiktokItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokLeadFormId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokOptimizeGoal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelEvent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokPixelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiktokRoasBid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "editWarning": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "learning_reset" ] }, { "type": "string", "enum": [ "recreate" ] }, { "type": "string", "enum": [ "re_review" ] }, { "type": "string", "enum": [ "id_change" ] } ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "create_all" ] }, { "type": "string", "enum": [ "ads_only" ] }, { "type": "string", "enum": [ "add_adset" ] } ] }, { "type": "null" } ] }, "sessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "source", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/campaign-templates/{id}": { "get": { "operationId": "getCampaignTemplate", "summary": "Get campaign template by ID", "tags": [ "campaigns" ], "description": "Retrieves a single campaign template by its UUID.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "source", "canonical_campaign", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "canonical_campaign": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteCampaignTemplate", "summary": "Delete campaign template", "tags": [ "campaigns" ], "description": "Soft-deletes a campaign template by its UUID.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/feeds": { "get": { "operationId": "getApiV1CatalogsByCatalogIdFeeds", "summary": "Get product feeds for a catalog", "tags": [ "catalog-feeds" ], "description": "Lists product feeds for a catalog the caller can access, returning feed identity, schedule metadata, and latest upload status when Meta provides it.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "schedule": { "type": "object", "properties": { "url": { "type": "string" }, "interval": { "type": "string" }, "hour": { "type": "number" } } }, "latest_upload": { "type": "object", "properties": { "end_time": { "type": "string" }, "status": { "type": "string" } } } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CatalogsByCatalogIdFeeds", "summary": "Create a product feed", "tags": [ "catalog-feeds" ], "description": "Creates a Meta product feed under the selected catalog, optionally configuring the scheduled fetch URL, interval, and fetch hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "schedule_url": { "format": "uri", "type": "string" }, "interval": { "anyOf": [ { "type": "string", "enum": [ "HOURLY" ] }, { "type": "string", "enum": [ "DAILY" ] }, { "type": "string", "enum": [ "WEEKLY" ] } ] }, "hour": { "minimum": 0, "maximum": 23, "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/feeds/{feedId}": { "put": { "operationId": "putApiV1CatalogsByCatalogIdFeedsByFeedId", "summary": "Update a product feed", "tags": [ "catalog-feeds" ], "description": "Updates mutable metadata for an existing product feed in a catalog the caller can access; currently supports renaming the feed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "feedId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CatalogsByCatalogIdFeedsByFeedId", "summary": "Delete a product feed", "tags": [ "catalog-feeds" ], "description": "Deletes the selected Meta product feed after verifying catalog access and an authorized token for the catalog business.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "feedId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/feeds/{feedId}/upload": { "post": { "operationId": "postApiV1CatalogsByCatalogIdFeedsByFeedIdUpload", "summary": "Upload to a product feed", "tags": [ "catalog-feeds" ], "description": "Starts a Meta feed upload from a publicly reachable file URL for the selected feed and returns the upload session id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "format": "uri", "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "feedId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/feeds/{feedId}/uploads": { "get": { "operationId": "getApiV1CatalogsByCatalogIdFeedsByFeedIdUploads", "summary": "Get feed uploads", "tags": [ "catalog-feeds" ], "description": "Lists upload sessions for the selected product feed, including upload status, source URL, and completion time when available.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "feedId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "end_time": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/feeds/{feedId}/uploads/{uploadId}/errors": { "get": { "operationId": "getApiV1CatalogsByCatalogIdFeedsByFeedIdUploadsByUploadIdErrors", "summary": "Get per-row errors for a feed upload session", "tags": [ "catalog-feeds" ], "description": "Returns import validation errors for a feed upload session, including severity, row number, retailer id, and the Meta error message when available.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "feedId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "uploadId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "severity": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "row_number": { "type": "number" }, "retailer_id": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products": { "get": { "operationId": "listCatalogProducts", "summary": "List products in a catalog", "tags": [ "catalog-products" ], "description": "Returns products from Meta Graph API for the given catalog (cursor-paginated). Shape mirrors Meta Graph v25.0 projected fields; additional fields are preserved as pass-through.", "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "after", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "sale_price": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "string" }, "condition": { "type": "string" }, "image_url": { "type": "string" }, "url": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "product_type": { "type": "string" }, "retailer_id": { "type": "string" }, "custom_label_0": { "type": "string" }, "custom_label_1": { "type": "string" }, "custom_label_2": { "type": "string" }, "custom_label_3": { "type": "string" }, "custom_label_4": { "type": "string" }, "description": { "type": "string" }, "review_status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "visibility": { "type": "string" }, "item_group_id": { "type": "string" }, "additional_image_urls": { "type": "array", "items": { "type": "string" } }, "video": { "anyOf": [ { "type": "null" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" } } } ] } } } }, "paging": { "type": "object", "properties": { "cursors": { "type": "object", "properties": { "after": { "type": "string" }, "before": { "type": "string" } } }, "next": { "type": "string" }, "previous": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CatalogsByCatalogIdProducts", "summary": "Create a product in catalog", "tags": [ "catalog-products" ], "description": "Creates a product item in the selected Meta catalog. Price fields are normalized before submission and item_group_id is sent as retailer_product_group_id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "retailer_id", "name", "availability", "price", "currency", "image_url" ], "properties": { "retailer_id": { "minLength": 1, "maxLength": 500, "type": "string" }, "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "availability": { "anyOf": [ { "type": "string", "enum": [ "in stock" ] }, { "type": "string", "enum": [ "out of stock" ] }, { "type": "string", "enum": [ "available for order" ] }, { "type": "string", "enum": [ "discontinued" ] } ] }, "price": { "anyOf": [ { "minLength": 1, "maxLength": 50, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, "currency": { "minLength": 3, "maxLength": 3, "type": "string" }, "image_url": { "minLength": 1, "maxLength": 2000, "pattern": "\\S", "type": "string" }, "url": { "maxLength": 2000, "type": "string" }, "description": { "maxLength": 5000, "type": "string" }, "brand": { "maxLength": 200, "type": "string" }, "category": { "maxLength": 500, "type": "string" }, "condition": { "anyOf": [ { "type": "string", "enum": [ "new" ] }, { "type": "string", "enum": [ "refurbished" ] }, { "type": "string", "enum": [ "used" ] } ] }, "sale_price": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "minimum": 0, "type": "integer" } ] }, "custom_label_0": { "maxLength": 100, "type": "string" }, "custom_label_1": { "maxLength": 100, "type": "string" }, "custom_label_2": { "maxLength": 100, "type": "string" }, "custom_label_3": { "maxLength": 100, "type": "string" }, "custom_label_4": { "maxLength": 100, "type": "string" }, "item_group_id": { "maxLength": 100, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/{productId}": { "get": { "operationId": "getCatalogProduct", "summary": "Get single product details", "tags": [ "catalog-products" ], "description": "Fetches a single product node from Meta Graph API. Known fields are typed against Meta Graph v25.0; additional fields are preserved (pass-through).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "sale_price": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "string" }, "condition": { "type": "string" }, "image_url": { "type": "string" }, "url": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "product_type": { "type": "string" }, "retailer_id": { "type": "string" }, "custom_label_0": { "type": "string" }, "custom_label_1": { "type": "string" }, "custom_label_2": { "type": "string" }, "custom_label_3": { "type": "string" }, "custom_label_4": { "type": "string" }, "description": { "type": "string" }, "review_status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "visibility": { "type": "string" }, "item_group_id": { "type": "string" }, "additional_image_urls": { "type": "array", "items": { "type": "string" } }, "video": { "anyOf": [ { "type": "null" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" } } } ] }, "video_urls": { "type": "array", "items": { "type": "string" } }, "videos": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "updated_time": { "type": "string" } } } }, "paging": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "put": { "operationId": "putApiV1CatalogsByCatalogIdProductsByProductId", "summary": "Update a product", "tags": [ "catalog-products" ], "description": "Updates mutable fields on an existing Meta catalog product. Price fields are normalized before submission and item_group_id is sent as retailer_product_group_id. `image_url`, if provided, must be non-empty - a catalog product must always keep an image, so clearing it is rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "retailer_id" ], "properties": { "retailer_id": { "minLength": 1, "maxLength": 500, "type": "string" }, "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "availability": { "anyOf": [ { "type": "string", "enum": [ "in stock" ] }, { "type": "string", "enum": [ "out of stock" ] }, { "type": "string", "enum": [ "available for order" ] }, { "type": "string", "enum": [ "discontinued" ] } ] }, "price": { "maxLength": 50, "type": "string" }, "currency": { "minLength": 3, "maxLength": 3, "type": "string" }, "image_url": { "minLength": 1, "maxLength": 2000, "pattern": "\\S", "type": "string" }, "url": { "maxLength": 2000, "type": "string" }, "description": { "maxLength": 5000, "type": "string" }, "brand": { "maxLength": 200, "type": "string" }, "category": { "maxLength": 500, "type": "string" }, "condition": { "anyOf": [ { "type": "string", "enum": [ "new" ] }, { "type": "string", "enum": [ "refurbished" ] }, { "type": "string", "enum": [ "used" ] } ] }, "sale_price": { "maxLength": 50, "type": "string" }, "custom_label_0": { "maxLength": 100, "type": "string" }, "custom_label_1": { "maxLength": 100, "type": "string" }, "custom_label_2": { "maxLength": 100, "type": "string" }, "custom_label_3": { "maxLength": 100, "type": "string" }, "custom_label_4": { "maxLength": 100, "type": "string" }, "item_group_id": { "maxLength": 100, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CatalogsByCatalogIdProductsByProductId", "summary": "Delete a product from catalog", "tags": [ "catalog-products" ], "description": "Deletes the selected product item from the Meta catalog after verifying catalog access and token authorization.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/{productId}/request-review": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsByProductIdRequestReview", "summary": "Request re-review for a rejected product", "tags": [ "catalog-products" ], "description": "Triggers Meta re-review for a rejected product by resending the current product name as a minimal update payload.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/{productId}/archive": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsByProductIdArchive", "summary": "Archive a product (sets visibility=staging)", "tags": [ "catalog-products" ], "description": "Archives the selected product by setting Meta product visibility to staging while preserving existing product and ad set associations.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/{productId}/unarchive": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsByProductIdUnarchive", "summary": "Unarchive a product (sets visibility=published)", "tags": [ "catalog-products" ], "description": "Unarchives the selected product by setting Meta product visibility back to published for an accessible catalog.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/{productId}/videos": { "patch": { "operationId": "patchApiV1CatalogsByCatalogIdProductsByProductIdVideos", "summary": "Update product-level video URLs (max 20)", "tags": [ "catalog-products" ], "description": "Replaces product-level video URLs on the selected Meta catalog product with up to 20 absolute URL values. Meta requires the product to already have an image before it will accept a non-empty list - returns 400 `video_requires_image` otherwise (clearing the list back to empty is always allowed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "video_urls" ], "properties": { "video_urls": { "maxItems": 20, "type": "array", "items": { "format": "uri", "maxLength": 2048, "type": "string" } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "productId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/media/image": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsMediaImage", "summary": "Upload a product image and get back its public URL", "tags": [ "catalog-products" ], "description": "Stores a JPG/PNG/WebP file (max 10MB) in durable storage and returns its public URL. Does not modify the product — save the URL via PUT /catalogs/:catalogId/products/:productId (image_url) afterwards.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, or WebP product image (max 10MB)." } }, "additionalProperties": false } } } } } }, "/api/v1/catalogs/{catalogId}/products/media/video": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsMediaVideo", "summary": "Upload a product video and get back its public URL", "tags": [ "catalog-products" ], "description": "Stores an MP4/MOV file (max 100MB) in durable storage and returns its public URL. Does not modify the product — save the URL via PATCH /catalogs/:catalogId/products/:productId/videos afterwards.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "MP4 or MOV product video (max 100MB)." } }, "additionalProperties": false } } } } } }, "/api/v1/catalogs/{catalogId}/product-groups/{groupId}/variants": { "get": { "operationId": "getApiV1CatalogsByCatalogIdProductGroupsByGroupIdVariants", "summary": "List products sharing the same item_group_id (variants)", "tags": [ "catalog-products" ], "description": "Lists lightweight product variants in the catalog that share the supplied item_group_id or retailer_product_group_id.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "groupId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "retailer_id" ], "properties": { "id": { "type": "string" }, "retailer_id": { "type": "string" }, "name": { "type": "string" }, "image_url": { "type": "string" }, "price": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/batch": { "post": { "operationId": "postApiV1CatalogsByCatalogIdProductsBatch", "summary": "Batch product operations", "tags": [ "catalog-products" ], "description": "Dispatches asynchronous product operations for the selected Meta catalog and returns a batch run id with the initial RUNNING status. Each operation's `data.image_url`, if provided, must be non-empty. CREATE operations must also include a non-empty `data.image_url` - a catalog product must always have an image.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "operations" ], "properties": { "operations": { "minItems": 1, "maxItems": 50000, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "method", "retailer_id" ], "properties": { "method": { "anyOf": [ { "type": "string", "enum": [ "CREATE" ] }, { "type": "string", "enum": [ "UPDATE" ] }, { "type": "string", "enum": [ "DELETE" ] } ] }, "retailer_id": { "minLength": 1, "maxLength": 500, "type": "string" }, "data": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 500, "type": "string" }, "availability": { "maxLength": 50, "type": "string" }, "price": { "maxLength": 50, "type": "string" }, "currency": { "maxLength": 3, "type": "string" }, "image_url": { "minLength": 1, "maxLength": 2000, "pattern": "\\S", "type": "string" }, "url": { "maxLength": 2000, "type": "string" }, "description": { "maxLength": 5000, "type": "string" }, "brand": { "maxLength": 200, "type": "string" }, "category": { "maxLength": 500, "type": "string" }, "condition": { "maxLength": 50, "type": "string" }, "sale_price": { "maxLength": 50, "type": "string" }, "custom_label_0": { "maxLength": 100, "type": "string" }, "custom_label_1": { "maxLength": 100, "type": "string" }, "custom_label_2": { "maxLength": 100, "type": "string" }, "custom_label_3": { "maxLength": 100, "type": "string" }, "custom_label_4": { "maxLength": 100, "type": "string" } } } } } }, "allow_upsert": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "batch_run_id", "status", "operations_count" ], "properties": { "batch_run_id": { "type": "string" }, "status": { "type": "string" }, "operations_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/batch/{batchRunId}": { "get": { "operationId": "getApiV1CatalogsByCatalogIdProductsBatchByBatchRunId", "summary": "Get batch operation status", "tags": [ "catalog-products" ], "description": "Returns the latest status for a catalog product batch run accessible to the caller, including task counts, latest metadata, and error details.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "batchRunId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "batch_run_id", "status", "total_tasks", "completed_tasks", "failed_tasks", "metadata", "error", "created_at", "updated_at" ], "properties": { "batch_run_id": { "type": "string" }, "status": { "type": "string" }, "total_tasks": { "type": "integer" }, "completed_tasks": { "type": "integer" }, "failed_tasks": { "type": "integer" }, "metadata": { "anyOf": [ { "type": "null" }, { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalog": { "get": { "operationId": "getApiV1Catalog", "summary": "List unified catalog variants", "tags": [ "catalog" ], "description": "Lists team-scoped unified catalog variants with optional campaign, order, search, status, availability, and stock filters.", "parameters": [ { "schema": { "minLength": 1, "maxLength": 100, "type": "string" }, "in": "query", "name": "campaign_id", "required": false }, { "schema": { "minLength": 1, "maxLength": 1000, "type": "string" }, "in": "query", "name": "campaign_ids", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "id", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "order_id", "required": false }, { "schema": { "minLength": 1, "maxLength": 2000, "type": "string" }, "in": "query", "name": "order_ids", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "needs_review" ] }, { "type": "string", "enum": [ "inactive" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "available" ] }, { "type": "string", "enum": [ "unavailable" ] } ] }, "in": "query", "name": "availability", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "in_stock" ] }, { "type": "string", "enum": [ "low_stock" ] }, { "type": "string", "enum": [ "out_of_stock" ] } ] }, "in": "query", "name": "stock", "required": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "canonical_barcode", "canonical_brand", "canonical_gtin", "canonical_option_values", "canonical_sku", "canonical_title", "created_at", "deleted_at", "id", "merged_into_id", "needs_review", "product_master_id", "status", "team_id", "updated_at", "availability", "compare_at_price_amount", "cost_amount", "cost_currency", "description", "description_html", "image_urls", "price_amount", "price_currency", "primary_image_url", "resolved", "sources", "stock_policy", "stock_total", "tags", "weight_grams" ], "properties": { "canonical_barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "canonical_sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "merged_into_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "needs_review": { "type": "boolean" }, "product_master_id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "compare_at_price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_urls": { "type": "array", "items": { "type": "string" } }, "price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "price_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "field_provenance", "policy_snapshot_id", "resolved_at", "resolved_brand", "resolved_category_path", "resolved_description", "resolved_image_url", "resolved_tags", "resolved_title", "team_id", "variant_master_id" ], "properties": { "field_provenance": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "policy_snapshot_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "resolved_at": { "format": "date-time", "type": "string" }, "resolved_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_category_path": { "type": "array", "items": { "type": "string" } }, "resolved_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_tags": { "type": "array", "items": { "type": "string" } }, "resolved_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "display_name", "external_id", "external_product_id", "external_variant_id", "type" ], "properties": { "catalog_source_id": { "format": "uuid", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_variant_id": { "type": "string" }, "type": { "type": "string" } } } }, "stock_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stock_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "weight_grams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/spot-products": { "post": { "operationId": "postApiV1CatalogSpotProducts", "summary": "Create a manual spot product", "tags": [ "catalog" ], "description": "Creates a lightweight manual Store product and a matching Creative Hub product context for AI creative workflows.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ] }, "images": { "maxItems": 8, "type": "array", "items": { "maxLength": 2048, "type": "string" } }, "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "price": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "creative_product_id", "product_master_id", "variant_master_id" ], "properties": { "creative_product_id": { "format": "uuid", "type": "string" }, "product_master_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/spot-products/import-url": { "post": { "operationId": "postApiV1CatalogSpotProductsImportUrl", "summary": "Import a Store spot product from a product URL", "tags": [ "catalog" ], "description": "Scrapes a product URL and creates an editable manual Store product plus matching Creative Hub product context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 4, "maxLength": 2048, "type": "string" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "creative_product_id", "product_master_id", "variant_master_id" ], "properties": { "creative_product_id": { "format": "uuid", "type": "string" }, "product_master_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/spot-products/import-feed": { "post": { "operationId": "postApiV1CatalogSpotProductsImportFeed", "summary": "Import editable Store spot products from CSV", "tags": [ "catalog" ], "description": "Imports CSV rows into editable manual Store products. Supported headers: name, description, image_url, price, external_ref.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "csv" ], "properties": { "csv": { "minLength": 1, "maxLength": 2000000, "type": "string" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "imported", "items" ], "properties": { "imported": { "minimum": 0, "type": "integer" }, "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "creative_product_id", "product_master_id", "variant_master_id" ], "properties": { "creative_product_id": { "format": "uuid", "type": "string" }, "product_master_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/spot-products/{variant_master_id}": { "patch": { "operationId": "patchApiV1CatalogSpotProductsByVariantMasterId", "summary": "Update an editable Store spot product", "tags": [ "catalog" ], "description": "Updates product attributes only for manual Store products. Products linked to Shopify, WooCommerce, or another external provider are read-only here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "description": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ] }, "images": { "maxItems": 8, "type": "array", "items": { "maxLength": 2048, "type": "string" } }, "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "price": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "variant_master_id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "creative_product_id", "product_master_id", "variant_master_id" ], "properties": { "creative_product_id": { "format": "uuid", "type": "string" }, "product_master_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/{variant_master_id}": { "get": { "operationId": "getApiV1CatalogByVariantMasterId", "summary": "Get unified catalog variant detail", "tags": [ "catalog" ], "description": "Returns one team-scoped unified catalog variant with resolved fields, source links, related orders, resolved offers, and optional point-in-time catalog events.", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "as_of", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "variant_master_id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "as_of_events", "resolved", "resolved_offers", "variant" ], "properties": { "as_of_events": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "entity_id", "entity_type", "event_type", "external_entity_id", "id", "occurred_at", "payload_json", "recorded_at", "schema_version", "team_id" ], "properties": { "catalog_source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entity_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entity_type": { "type": "string" }, "event_type": { "type": "string" }, "external_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "payload_json": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "recorded_at": { "format": "date-time", "type": "string" }, "schema_version": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" } } } }, "resolved": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "field_provenance", "policy_snapshot_id", "resolved_at", "resolved_brand", "resolved_category_path", "resolved_description", "resolved_image_url", "resolved_tags", "resolved_title", "team_id", "variant_master_id" ], "properties": { "field_provenance": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "policy_snapshot_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "resolved_at": { "format": "date-time", "type": "string" }, "resolved_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_category_path": { "type": "array", "items": { "type": "string" } }, "resolved_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_tags": { "type": "array", "items": { "type": "string" } }, "resolved_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] }, "resolved_offers": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field_provenance", "id", "locale", "market_id", "policy_snapshot_id", "resolved_at", "resolved_availability", "resolved_compare_at_price_amount", "resolved_cost_amount", "resolved_cost_currency", "resolved_price_amount", "resolved_price_currency", "resolved_stock_total", "team_id", "variant_master_id" ], "properties": { "field_provenance": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "id": { "format": "uuid", "type": "string" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "market_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "policy_snapshot_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "resolved_at": { "format": "date-time", "type": "string" }, "resolved_availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_compare_at_price_amount": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, { "type": "null" } ] }, "resolved_cost_amount": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, { "type": "null" } ] }, "resolved_cost_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolved_price_amount": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, { "type": "null" } ] }, "resolved_price_currency": { "type": "string" }, "resolved_stock_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "team_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } }, "variant": { "additionalProperties": false, "type": "object", "required": [ "canonical_barcode", "canonical_brand", "canonical_gtin", "canonical_option_values", "canonical_sku", "canonical_title", "created_at", "deleted_at", "id", "merged_into_id", "needs_review", "product_master_id", "status", "team_id", "updated_at", "availability", "available_for_sale", "compare_at_price_amount", "cost_amount", "cost_currency", "description", "description_html", "image_urls", "price_amount", "price_currency", "primary_image_url", "related_orders", "sources", "stock_policy", "stock_total", "tags", "weight_grams" ], "properties": { "canonical_barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "canonical_sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "merged_into_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "needs_review": { "type": "boolean" }, "product_master_id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "available_for_sale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "compare_at_price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_urls": { "type": "array", "items": { "type": "string" } }, "price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "price_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "related_orders": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "effective_financial_status", "external_order_id", "financial_status", "fulfillment_status", "line_item_id", "net_amount", "order_id", "order_name", "placed_at", "qty", "sku", "source_type", "total_amount", "total_currency", "total_line_amount", "total_refunded", "unit_price_currency" ], "properties": { "effective_financial_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_order_id": { "type": "string" }, "financial_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line_item_id": { "type": "string" }, "net_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "order_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "order_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "qty": { "type": "integer" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_type": { "type": "string" }, "total_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total_line_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_refunded": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit_price_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "sources": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "display_name", "external_id", "external_product_id", "external_variant_id", "match_confidence", "match_reason", "source_data", "source_link_id", "status", "type" ], "properties": { "catalog_source_id": { "format": "uuid", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_variant_id": { "type": "string" }, "match_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "match_reason": { "type": "string" }, "source_data": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "availability", "available_for_sale", "barcode", "brand", "category_full_name", "category_name", "category_path", "category_source", "cdm_schema_version", "compare_at_price_amount", "cost_amount", "cost_currency", "description", "description_html", "external_retailer_id", "google_product_category_id", "gtin", "handle", "height_mm", "image_urls", "length_mm", "locale", "market_id", "marketplace_id", "match_confidence", "match_reason", "mpn", "option_values", "parent_external_id", "price_amount", "price_currency", "primary_image_url", "product_type", "published_at", "published_scope", "raw_payload", "recorded_at", "selected_option_values", "sku", "sku_raw", "source_created_at", "source_updated_at", "status", "stock_policy", "stock_total", "tags", "tax_included", "template_suffix", "title", "valid_from", "valid_to", "variant_type", "vendor", "weight_grams", "width_mm" ], "properties": { "availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "available_for_sale": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category_full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category_path": { "type": "array", "items": { "type": "string" } }, "category_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cdm_schema_version": { "type": "string" }, "compare_at_price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_retailer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "google_product_category_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "height_mm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "image_urls": { "type": "array", "items": { "type": "string" } }, "length_mm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "market_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "marketplace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "match_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "match_reason": { "type": "string" }, "mpn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "parent_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "price_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "published_scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_payload": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "selected_option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "source_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stock_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stock_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "tax_included": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "template_suffix": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valid_from": { "format": "date-time", "type": "string" }, "valid_to": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "variant_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "weight_grams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width_mm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "source_link_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" } } } }, "stock_policy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stock_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "weight_grams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog/{variant_master_id}/events": { "get": { "operationId": "getApiV1CatalogByVariantMasterIdEvents", "summary": "List catalog events for a variant", "tags": [ "catalog" ], "description": "Returns recent catalog events for a variant and for currently linked source products visible to the caller team.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "variant_master_id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "entity_id", "entity_type", "event_type", "external_entity_id", "id", "occurred_at", "payload_json", "recorded_at", "schema_version", "team_id" ], "properties": { "catalog_source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entity_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "entity_type": { "type": "string" }, "event_type": { "type": "string" }, "external_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "payload_json": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "recorded_at": { "format": "date-time", "type": "string" }, "schema_version": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/campaigns/{campaign_id}/products": { "get": { "operationId": "getApiV1CampaignsByCampaignIdProducts", "summary": "List product performance for a campaign", "tags": [ "catalog" ], "description": "Returns campaign-level product daily statistics for the current team, ordered by most recent stat date.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "campaign_id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "computed_at", "date", "fx_rate_date", "fx_source", "refunded_amount", "reporting_currency", "revenue_amount", "revenue_currency", "roas", "spend_amount", "team_id", "units_sold", "variant_master_id" ], "properties": { "campaign_id": { "type": "string" }, "computed_at": { "format": "date-time", "type": "string" }, "date": { "format": "date", "type": "string" }, "fx_rate_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "fx_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refunded_amount": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "reporting_currency": { "type": "string" }, "revenue_amount": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "revenue_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roas": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, { "type": "null" } ] }, "spend_amount": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "team_id": { "format": "uuid", "type": "string" }, "units_sold": { "type": "integer" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions": { "get": { "operationId": "getApiV1CatalogV2MatchSuggestions", "summary": "List catalog match suggestions", "tags": [ "catalog" ], "description": "Lists pending, approved, or rejected cross-source variant match suggestions with candidate/source snapshots and field diffs.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "in": "query", "name": "status", "required": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "candidate_product_master_id", "candidate_snapshot", "candidate_variant", "candidate_variant_master_id", "catalog_source_id", "confidence", "created_at", "decided_at", "decided_by", "external_product_id", "external_variant_id", "field_diffs", "id", "match_reasons", "score", "source", "source_snapshot", "source_variant", "status", "team_id", "updated_at" ], "properties": { "candidate_product_master_id": { "format": "uuid", "type": "string" }, "candidate_snapshot": { "additionalProperties": false, "type": "object", "required": [ "barcode", "brand", "gtin", "option_values", "sku", "title" ], "properties": { "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "candidate_variant": { "additionalProperties": false, "type": "object", "required": [ "canonical_barcode", "canonical_brand", "canonical_gtin", "canonical_option_values", "canonical_sku", "canonical_title", "id", "image_urls", "primary_image_url", "product_master_id", "updated_at" ], "properties": { "canonical_barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "canonical_sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string" } }, "primary_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_master_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "candidate_variant_master_id": { "format": "uuid", "type": "string" }, "catalog_source_id": { "format": "uuid", "type": "string" }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "very_high" ] }, { "type": "string", "enum": [ "high" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "low" ] } ] }, "created_at": { "format": "date-time", "type": "string" }, "decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "decided_by": { "type": "null" }, "external_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_variant_id": { "type": "string" }, "field_diffs": { "additionalProperties": false, "type": "object", "required": [ "barcode", "brand", "gtin", "option_values", "sku", "title" ], "properties": { "barcode": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } }, "brand": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } }, "gtin": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } }, "option_values": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } }, "sku": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } }, "title": { "additionalProperties": false, "type": "object", "required": [ "candidate", "source" ], "properties": { "candidate": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "source": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } } } }, "id": { "format": "uuid", "type": "string" }, "match_reasons": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number" }, "source": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "display_name", "external_id", "id", "status", "type" ], "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" } } }, { "type": "null" } ] }, "source_snapshot": { "additionalProperties": false, "type": "object", "required": [ "barcode", "brand", "gtin", "option_values", "sku", "title" ], "properties": { "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "source_variant": { "additionalProperties": false, "type": "object", "required": [ "barcode", "brand", "catalog_source_id", "external_id", "gtin", "image_urls", "option_values", "parent_external_id", "primary_image_url", "sku", "title" ], "properties": { "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalog_source_id": { "format": "uuid", "type": "string" }, "external_id": { "type": "string" }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_urls": { "type": "array", "items": { "type": "string" } }, "option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "parent_external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "team_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions/{id}/accept": { "post": { "operationId": "postApiV1CatalogV2MatchSuggestionsByIdAccept", "summary": "Accept a catalog match suggestion", "tags": [ "catalog" ], "description": "Approves a pending source-link match suggestion and clears review state when no pending suggestions remain for the variant.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "suggestion" ], "properties": { "suggestion": { "additionalProperties": false, "type": "object", "required": [ "id", "status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] } ] } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions/{id}/reject": { "post": { "operationId": "postApiV1CatalogV2MatchSuggestionsByIdReject", "summary": "Reject a catalog match suggestion", "tags": [ "catalog" ], "description": "Rejects a pending source-link match suggestion, unlinks it, and clears review state when appropriate.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "suggestion" ], "properties": { "suggestion": { "additionalProperties": false, "type": "object", "required": [ "id", "status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] } ] } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions/{id}/create-separate": { "post": { "operationId": "postApiV1CatalogV2MatchSuggestionsByIdCreateSeparate", "summary": "Create a separate variant from a match suggestion", "tags": [ "catalog" ], "description": "Turns a pending source variant into a new canonical product/variant and records the original suggestion as separated.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "variant" ], "properties": { "variant": { "additionalProperties": false, "type": "object", "required": [ "canonical_barcode", "canonical_brand", "canonical_gtin", "canonical_option_values", "canonical_sku", "canonical_title", "created_at", "deleted_at", "id", "merged_into_id", "needs_review", "product_master_id", "status", "team_id", "updated_at" ], "properties": { "canonical_barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_option_values": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "canonical_sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "merged_into_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "needs_review": { "type": "boolean" }, "product_master_id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions/bulk/auto-resolve-safe": { "post": { "operationId": "postApiV1CatalogV2MatchSuggestionsBulkAutoResolveSafe", "summary": "Auto-resolve safe catalog match suggestions", "tags": [ "catalog" ], "description": "Approves selected pending match suggestions whose confidence is at least 0.95, or returns a dry-run preview.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "suggestion_ids" ], "properties": { "dry_run": { "type": "boolean" }, "suggestion_ids": { "type": "array", "items": { "format": "uuid", "type": "string" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "preview", "resolved_count" ], "properties": { "preview": { "additionalProperties": false, "type": "object", "required": [ "auto_link", "conflicts", "selected", "still_need_review" ], "properties": { "auto_link": { "type": "integer" }, "conflicts": { "type": "integer" }, "selected": { "type": "integer" }, "still_need_review": { "type": "integer" } } }, "resolved_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/match-suggestions/bulk/reject": { "post": { "operationId": "postApiV1CatalogV2MatchSuggestionsBulkReject", "summary": "Bulk reject catalog match suggestions", "tags": [ "catalog" ], "description": "Rejects selected pending match suggestions, unlinks them, clears review flags, and records catalog events.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "suggestion_ids" ], "properties": { "reason": { "type": "string" }, "suggestion_ids": { "type": "array", "items": { "format": "uuid", "type": "string" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "rejected_count" ], "properties": { "rejected_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/variants/merge": { "post": { "operationId": "postApiV1VariantsMerge", "summary": "Merge catalog variants", "tags": [ "catalog" ], "description": "Queues an asynchronous merge of loser variants into a winner variant and supports idempotent retry through the idempotency key header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "winner_id", "loser_ids", "reason" ], "properties": { "winner_id": { "format": "uuid", "type": "string" }, "loser_ids": { "minItems": 1, "type": "array", "items": { "format": "uuid", "type": "string" } }, "reason": { "minLength": 1, "type": "string" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "duplicate" ] } ] } } } } } }, "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "status" ], "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "duplicate" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/variants/{id}/split": { "post": { "operationId": "postApiV1VariantsByIdSplit", "summary": "Split a merged catalog variant", "tags": [ "catalog" ], "description": "Restores a merged variant to active review state and removes aliases so source links can be reassigned manually.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/catalog-v2/source-links/{id}/undo": { "post": { "operationId": "postApiV1CatalogV2SourceLinksByIdUndo", "summary": "Undo a source link removal", "tags": [ "catalog" ], "description": "Reactivates a previously unlinked source-to-variant link and records the undo action as a catalog event.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "source_link" ], "properties": { "source_link": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "external_product_id", "external_retailer_id", "external_variant_id", "id", "linked_at", "market_id", "match_confidence", "match_reason", "team_id", "unlinked_at", "variant_master_id" ], "properties": { "catalog_source_id": { "format": "uuid", "type": "string" }, "external_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_retailer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_variant_id": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "linked_at": { "format": "date-time", "type": "string" }, "market_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "match_confidence": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "match_reason": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "unlinked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/variants/{id}/override": { "post": { "operationId": "postApiV1VariantsByIdOverride", "summary": "Create a variant field override", "tags": [ "catalog" ], "description": "Stores a manual field override or forced source selection for a team-owned catalog variant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "field_name", "override_type", "reason" ], "properties": { "field_name": { "type": "string" }, "override_type": { "type": "string" }, "override_value": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "forced_source_id": { "format": "uuid", "type": "string" }, "reason": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "created_at", "expires_at", "field_name", "forced_source_id", "id", "override_type", "override_value", "reason", "revoked_at", "team_id", "user_id", "variant_master_id" ], "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "field_name": { "type": "string" }, "forced_source_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "override_type": { "type": "string" }, "override_value": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "reason": { "type": "string" }, "revoked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "team_id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "variant_master_id": { "format": "uuid", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/integrations/{id}/progress": { "get": { "operationId": "getApiV1IntegrationsByIdProgress", "summary": "Get catalog integration sync progress", "tags": [ "catalog" ], "description": "Returns sync progress rows for a catalog source after verifying the caller can read the owning team.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_source_id", "completed_at", "created_at", "id", "items_processed", "items_total", "last_error", "last_line_number", "phase", "started_at", "status", "team_id", "updated_at" ], "properties": { "catalog_source_id": { "format": "uuid", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "items_processed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "items_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_line_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "phase": { "type": "string" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/integrations/shopify/callback": { "post": { "operationId": "postApiV1IntegrationsShopifyCallback", "summary": "Register a Shopify catalog source callback", "tags": [ "catalog" ], "description": "Creates the Shopify catalog source record for an authorized team after OAuth/callback setup completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "team_id", "shop_domain" ], "properties": { "team_id": { "format": "uuid", "type": "string" }, "shop_domain": { "type": "string" }, "shopify_config_id": { "format": "uuid", "type": "string" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "config_json", "connected_at", "created_at", "deleted_at", "disconnected_at", "display_name", "external_id", "id", "shopify_config_id", "status", "team_id", "type", "updated_at", "woocommerce_config_id" ], "properties": { "config_json": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "connected_at": { "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "disconnected_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "external_id": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "shopify_config_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "type": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "woocommerce_config_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/catalogs": { "get": { "operationId": "listCatalogs", "summary": "Get catalogs (server-side paginated)", "tags": [ "catalogs" ], "description": "Returns a server-side paginated, filtered, sorted list of Meta Catalogs. Supports offset pagination, search, and multiple filter dimensions.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "member_id", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "catalog_name" ] }, { "type": "string", "enum": [ "business_name" ] }, { "type": "string", "enum": [ "vertical" ] }, { "type": "string", "enum": [ "product_count" ] }, { "type": "string", "enum": [ "connected" ] }, { "type": "string", "enum": [ "created_at" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_order", "required": false }, { "schema": { "minLength": 2, "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] }, "in": "query", "name": "connected", "required": false }, { "schema": { "maxLength": 50, "type": "string" }, "in": "query", "name": "vertical", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] }, "in": "query", "name": "is_active", "required": false }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "business_id", "required": false }, { "schema": { "maxLength": 10, "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_to", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "counts" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "catalog_id", "catalog_name", "business_id", "business_name", "vertical", "product_count", "connected", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "catalog_id": { "type": "string" }, "catalog_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "business_id": { "type": "string" }, "business_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_count": { "type": "integer" }, "connected": { "type": "boolean" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "member_email": { "type": "string" } } } }, "total": { "type": "integer" }, "counts": { "type": "object", "required": [ "connected", "disconnected" ], "properties": { "connected": { "type": "integer" }, "disconnected": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "createCatalog", "summary": "Create a new catalog on Meta", "tags": [ "catalogs" ], "description": "Creates a Meta product catalog under the specified business, stores the catalog locally, and marks it connected for the resolved caller session.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "vertical", "business_id" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "vertical": { "anyOf": [ { "type": "string", "enum": [ "commerce" ] }, { "type": "string", "enum": [ "hotels" ] }, { "type": "string", "enum": [ "flights" ] }, { "type": "string", "enum": [ "destinations" ] }, { "type": "string", "enum": [ "vehicles" ] }, { "type": "string", "enum": [ "home_listings" ] } ] }, "business_id": { "minLength": 1, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "catalog_id", "message" ], "properties": { "catalog_id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/businesses": { "get": { "operationId": "listCatalogBusinesses", "summary": "List businesses for catalog filters", "tags": [ "catalogs" ], "description": "Returns distinct Meta Business Manager ids and names represented by catalogs visible to the caller, respecting admin/team scoping.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/verticals": { "get": { "operationId": "listCatalogVerticals", "summary": "List verticals for catalog filters", "tags": [ "catalogs" ], "description": "Returns distinct Meta catalog vertical values visible to the caller so clients can populate catalog filters without scanning the full catalog list.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/connect": { "post": { "operationId": "connectCatalogs", "summary": "Connect catalogs", "tags": [ "catalogs" ], "description": "Sets the connected flag to true for the specified catalogs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "catalogs" ], "properties": { "catalogs": { "minItems": 1, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_id", "business_id" ], "properties": { "catalog_id": { "type": "string" }, "business_id": { "type": "string" } } } }, "sheet_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/disconnect": { "post": { "operationId": "disconnectCatalogs", "summary": "Disconnect catalogs", "tags": [ "catalogs" ], "description": "Sets the connected flag to false for the specified catalogs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "catalogs" ], "properties": { "catalogs": { "minItems": 1, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "catalog_id", "business_id" ], "properties": { "catalog_id": { "type": "string" }, "business_id": { "type": "string" } } } }, "sheet_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/product-sets": { "get": { "operationId": "listCatalogProductSets", "summary": "Get product sets for a catalog", "tags": [ "catalogs" ], "description": "Returns product sets for the given catalog from Meta API in real-time. Supports pagination via next_page_url.", "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "next_page_url", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "filter", "product_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filter": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "product_count": { "type": "integer" } } } }, "next_page_url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "createCatalogProductSet", "summary": "Create a product set", "tags": [ "catalogs" ], "description": "Creates a new product set in the given catalog via Meta API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "filter": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filter", "product_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filter": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "product_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/product-sets/{setId}/products": { "get": { "operationId": "listProductSetProducts", "summary": "Get products for a product set", "tags": [ "catalogs" ], "description": "Returns products for the given product set from Meta API in real-time. Supports pagination via next_page_url.", "parameters": [ { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "next_page_url", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "setId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "retailer_id" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "sale_price": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "string" }, "condition": { "type": "string" }, "image_url": { "type": "string" }, "url": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" }, "product_type": { "type": "string" }, "retailer_id": { "type": "string" }, "custom_label_0": { "type": "string" }, "custom_label_1": { "type": "string" }, "custom_label_2": { "type": "string" }, "custom_label_3": { "type": "string" }, "custom_label_4": { "type": "string" }, "description": { "type": "string" }, "review_status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "visibility": { "type": "string" }, "item_group_id": { "type": "string" }, "additional_image_urls": { "type": "array", "items": { "type": "string" } }, "video": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" } } }, { "type": "null" } ] }, "in_active_campaign": { "type": "boolean" } } } }, "next_page_url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/video/{videoId}": { "get": { "operationId": "getCatalogVideoSource", "summary": "Get video source URL", "tags": [ "catalogs" ], "description": "Returns the playable source URL for a product video from Meta API.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "videoId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/connect-pixel": { "post": { "operationId": "connectCatalogPixel", "summary": "Connect a pixel to a catalog", "tags": [ "catalogs" ], "description": "Assigns a Meta Pixel as an external event source for the given catalog.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "pixel_id" ], "properties": { "pixel_id": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/disconnect-pixel": { "post": { "operationId": "disconnectCatalogPixel", "summary": "Disconnect a pixel from a catalog", "tags": [ "catalogs" ], "description": "Removes a Meta Pixel as an external event source from the given catalog.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "pixel_id" ], "properties": { "pixel_id": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/pixels": { "get": { "operationId": "listCatalogPixels", "summary": "Get pixels connected to a catalog", "tags": [ "catalogs" ], "description": "Returns the list of Meta Pixels (external event sources) connected to the given catalog.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/share-permissions": { "post": { "operationId": "shareCatalogPermissions", "summary": "Share catalog permissions with business users", "tags": [ "catalogs" ], "description": "Assigns the specified permission level on a catalog to one or more business users.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "business_user_ids", "business_id", "permission_level" ], "properties": { "business_user_ids": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "business_id": { "type": "string" }, "permission_level": { "anyOf": [ { "type": "string", "enum": [ "FULL" ] }, { "type": "string", "enum": [ "ADVERTISE" ] } ] } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "total_success", "total_failed" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "asset_id", "business_user_id", "status" ], "properties": { "asset_id": { "type": "string" }, "business_user_id": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "SUCCESS" ] }, { "type": "string", "enum": [ "FAILED" ] } ] }, "error": { "type": "string" } } } }, "total_success": { "type": "integer" }, "total_failed": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/products/preview": { "post": { "operationId": "previewCatalogProducts", "summary": "Preview products matching a filter", "tags": [ "catalogs" ], "description": "Returns up to `limit` products in the catalog matching the given filter, enriched with an in_active_campaign flag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "filter": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "limit": { "minimum": 1, "maximum": 100, "default": 25, "type": "integer" }, "next_page_url": { "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "price", "currency", "availability", "image_url", "retailer_id", "in_active_campaign" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "currency": { "type": "string" }, "availability": { "type": "string" }, "image_url": { "type": "string" }, "retailer_id": { "type": "string" }, "in_active_campaign": { "type": "boolean" } } } }, "next_page_url": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/product-sets/{setId}": { "get": { "operationId": "getCatalogProductSet", "summary": "Get product set details", "tags": [ "catalogs" ], "description": "Returns details (name, filter, product count) for a single product set from Meta API.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "setId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filter", "product_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filter": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "product_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "put": { "operationId": "updateCatalogProductSet", "summary": "Update a product set", "tags": [ "catalogs" ], "description": "Updates name and/or filter of an existing product set via Meta API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 500, "type": "string" }, "filter": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "setId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filter", "product_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filter": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] }, "product_count": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteCatalogProductSet", "summary": "Delete a product set", "tags": [ "catalogs" ], "description": "Permanently deletes a product set from the catalog via Meta API.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "setId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}": { "patch": { "operationId": "updateCatalog", "summary": "Update a catalog on Meta", "tags": [ "catalogs" ], "description": "Updates mutable catalog fields on Meta, currently the catalog name, and mirrors the changed name into the local catalog row.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteCatalog", "summary": "Delete a catalog from Meta", "tags": [ "catalogs" ], "description": "Deletes the catalog from Meta using a team-scoped token and removes or deactivates the local catalog representation when the upstream delete succeeds.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/diagnostics": { "get": { "operationId": "getCatalogDiagnostics", "summary": "Get catalog diagnostics", "tags": [ "catalogs" ], "description": "Returns diagnostics for a catalog from Meta API with 30-minute cache.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "diagnostics", "event_stats", "cached" ], "properties": { "diagnostics": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "event_stats": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "cached": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/catalogs/{catalogId}/event-stats": { "get": { "operationId": "getCatalogEventStats", "summary": "Get catalog event stats", "tags": [ "catalogs" ], "description": "Returns event stats for a catalog from Meta API with 30-minute cache.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "catalogId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "event_stats", "cached" ], "properties": { "event_stats": { "type": "array", "items": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "cached": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/chat/presets": { "get": { "operationId": "getApiV1ChatPresets", "summary": "List AI Chat presets", "tags": [ "ai-chat" ], "description": "Returns visible personal, team, and managed AI chat presets for the authenticated user.", "parameters": [ { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "include_deleted", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "allowed_sources", "category", "created_at", "default_context_schema", "description", "id", "metadata", "name", "output_format", "owner_id", "prompt", "required_input_schema", "risk_tier", "team_id", "updated_at", "usage_count", "version", "visibility" ], "properties": { "allowed_sources": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$comment": "json-value" }, "name": { "type": "string" }, "output_format": { "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "prompt": { "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "usage_count": { "type": "integer" }, "version": { "type": "integer" }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "personal" ] }, { "type": "string", "enum": [ "team" ] }, { "type": "string", "enum": [ "managed" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiV1ChatPresets", "summary": "Create an AI Chat preset", "tags": [ "ai-chat" ], "description": "Creates a personal, team, or managed AI chat preset with its prompt and JSON input contracts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "prompt", "visibility" ], "properties": { "allowed_sources": { "maxItems": 12, "type": "array", "items": { "maxLength": 80, "type": "string" } }, "category": { "maxLength": 40, "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value" }, "name": { "minLength": 1, "maxLength": 120, "type": "string" }, "output_format": { "maxLength": 40, "type": "string" }, "prompt": { "minLength": 1, "maxLength": 8000, "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "personal" ] }, { "type": "string", "enum": [ "team" ] }, { "type": "string", "enum": [ "managed" ] } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "allowed_sources", "category", "created_at", "default_context_schema", "description", "id", "metadata", "name", "output_format", "owner_id", "prompt", "required_input_schema", "risk_tier", "team_id", "updated_at", "usage_count", "version", "visibility" ], "properties": { "allowed_sources": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$comment": "json-value" }, "name": { "type": "string" }, "output_format": { "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "prompt": { "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "usage_count": { "type": "integer" }, "version": { "type": "integer" }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "personal" ] }, { "type": "string", "enum": [ "team" ] }, { "type": "string", "enum": [ "managed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/chat/presets/{id}": { "patch": { "operationId": "patchApiV1ChatPresetsById", "summary": "Update an AI Chat preset", "tags": [ "ai-chat" ], "description": "Updates editable fields on an existing AI chat preset visible to the authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "allowed_sources": { "maxItems": 12, "type": "array", "items": { "maxLength": 80, "type": "string" } }, "category": { "maxLength": 40, "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value" }, "name": { "minLength": 1, "maxLength": 120, "type": "string" }, "output_format": { "maxLength": 40, "type": "string" }, "prompt": { "minLength": 1, "maxLength": 8000, "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "allowed_sources", "category", "created_at", "default_context_schema", "description", "id", "metadata", "name", "output_format", "owner_id", "prompt", "required_input_schema", "risk_tier", "team_id", "updated_at", "usage_count", "version", "visibility" ], "properties": { "allowed_sources": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$comment": "json-value" }, "name": { "type": "string" }, "output_format": { "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "prompt": { "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "usage_count": { "type": "integer" }, "version": { "type": "integer" }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "personal" ] }, { "type": "string", "enum": [ "team" ] }, { "type": "string", "enum": [ "managed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } }, "delete": { "operationId": "deleteApiV1ChatPresetsById", "summary": "Delete an AI Chat preset", "tags": [ "ai-chat" ], "description": "Soft-deletes an AI chat preset within the user accessible scope.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/chat/presets/{id}/use": { "post": { "operationId": "postApiV1ChatPresetsByIdUse", "summary": "Record AI Chat preset usage", "tags": [ "ai-chat" ], "description": "Increments usage counters and returns the selected AI chat preset.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "allowed_sources", "category", "created_at", "default_context_schema", "description", "id", "metadata", "name", "output_format", "owner_id", "prompt", "required_input_schema", "risk_tier", "team_id", "updated_at", "usage_count", "version", "visibility" ], "properties": { "allowed_sources": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "default_context_schema": { "$comment": "json-value" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "metadata": { "$comment": "json-value" }, "name": { "type": "string" }, "output_format": { "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "prompt": { "type": "string" }, "required_input_schema": { "$comment": "json-value" }, "risk_tier": { "anyOf": [ { "type": "string", "enum": [ "low" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "high" ] } ] }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "usage_count": { "type": "integer" }, "version": { "type": "integer" }, "visibility": { "anyOf": [ { "type": "string", "enum": [ "personal" ] }, { "type": "string", "enum": [ "team" ] }, { "type": "string", "enum": [ "managed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "statusCode" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/chat/projects": { "get": { "operationId": "getApiV1ChatProjects", "summary": "List chat projects", "tags": [ "ai-chat" ], "description": "Returns all chat projects for the authenticated user.", "parameters": [ { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "include_archived", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "name", "description", "instructions", "color", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "files": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "file_name", "file_type", "file_size", "created_at" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "file_type": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } }, "chat_count": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "postApiV1ChatProjects", "summary": "Create a chat project", "tags": [ "ai-chat" ], "description": "Creates a standalone AI chat project for organizing sessions and project file references.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "description": { "maxLength": 2000, "type": "string" }, "instructions": { "maxLength": 5000, "type": "string" }, "color": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, "memory_enabled": { "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "name", "description", "instructions", "color", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "files": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "file_name", "file_type", "file_size", "created_at" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "file_type": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } }, "chat_count": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/projects/{id}": { "get": { "operationId": "getApiV1ChatProjectsById", "summary": "Get chat project details", "tags": [ "ai-chat" ], "description": "Returns one chat project with files, memory flag, and active chat count.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "name", "description", "instructions", "color", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "files": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "file_name", "file_type", "file_size", "created_at" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "file_type": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } }, "chat_count": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1ChatProjectsById", "summary": "Update a chat project", "tags": [ "ai-chat" ], "description": "Updates chat project metadata, archive state, and optional memory flag.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "description": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "maxLength": 5000, "type": "string" }, { "type": "null" } ] }, "color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "is_archived": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "name", "description", "instructions", "color", "is_archived", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "files": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "file_name", "file_type", "file_size", "created_at" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "file_type": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } }, "chat_count": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1ChatProjectsById", "summary": "Delete a chat project", "tags": [ "ai-chat" ], "description": "Deletes a chat project. Chat sessions are unlinked (not deleted).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat/projects/{id}/files": { "post": { "operationId": "postApiV1ChatProjectsByIdFiles", "summary": "Add a file reference to a chat project", "tags": [ "ai-chat" ], "description": "Adds an already uploaded supported file reference to a chat project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "file_name", "file_url", "file_type" ], "properties": { "file_name": { "minLength": 1, "maxLength": 500, "type": "string" }, "file_url": { "minLength": 1, "type": "string" }, "file_type": { "minLength": 1, "maxLength": 120, "type": "string" }, "file_size": { "minimum": 0, "type": "integer" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "file_name", "file_type", "file_size", "created_at" ], "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "file_type": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat/projects/{id}/files/{fileId}": { "delete": { "operationId": "deleteApiV1ChatProjectsByIdFilesByFileId", "summary": "Remove a file from a chat project", "tags": [ "ai-chat" ], "description": "Removes a file reference from a chat project owned by the authenticated user.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat/projects/{id}/sessions/{sessionId}": { "post": { "operationId": "postApiV1ChatProjectsByIdSessionsBySessionId", "summary": "Assign a chat session to a project", "tags": [ "ai-chat" ], "description": "Links an existing chat session to a chat project owned by the authenticated user.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "sessionId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1ChatProjectsByIdSessionsBySessionId", "summary": "Remove a chat session from a project", "tags": [ "ai-chat" ], "description": "Unlinks a chat session from a chat project without deleting the session.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "sessionId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat-upload": { "post": { "operationId": "chatUploadFile", "summary": "Upload file for chat attachment", "tags": [ "ai-chat" ], "description": "Accepts a single file (max 10MB, enforced via the multipart limits registered on this route) and uploads to S3 or local filesystem. Supported MIME types: jpeg, png, webp, gif, pdf, csv, txt, markdown, ms-excel (Windows-exported CSV), docx, xlsx. HEIC/HEIF photos are rejected (415) with guidance to convert to JPEG.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "fileName", "fileType", "fileSize" ], "properties": { "url": { "description": "Public/CDN URL to retrieve the uploaded file", "type": "string" }, "fileName": { "description": "Original filename (or generated UUID if not provided)", "type": "string" }, "fileType": { "description": "MIME type of the uploaded file", "type": "string" }, "fileSize": { "description": "File size in bytes", "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "415": { "description": "Response 415", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat-voice/transcribe": { "post": { "operationId": "chatVoiceTranscribe", "summary": "Transcribe audio via OpenAI Whisper API", "tags": [ "ai-chat" ], "description": "Accepts audio file (webm/mp3/wav, max 25MB per Whisper API limit; see plugin 13-multipart for global limits) and returns transcribed text. Used as fallback when browser SpeechRecognition is unavailable. The optional `language` query parameter (BCP-47 code) hints Whisper; if omitted, Whisper auto-detects the spoken language.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "language", "required": false, "description": "Language hint for Whisper (BCP-47, e.g. \"it\", \"en\"). Default \"it\"." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "description": "Transcribed text from the audio input", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat/sessions": { "get": { "operationId": "getApiV1ChatSessions", "summary": "List chat sessions", "tags": [ "ai-chat" ], "description": "Returns a paginated list of the user's AI chat sessions.", "parameters": [ { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "project_id", "required": false }, { "schema": { "default": false, "type": "boolean" }, "in": "query", "name": "archived", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "title", "created_at", "updated_at", "project_id", "is_favorite", "last_message", "message_count" ], "properties": { "id": { "format": "uuid", "type": "string" }, "title": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "is_favorite": { "type": "boolean" }, "last_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message_count": { "type": "integer" } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } }, "post": { "operationId": "postApiV1ChatSessions", "summary": "Create a new AI chat session", "tags": [ "ai-chat" ], "description": "Creates a new AI chat session for the authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "project_id": { "type": "string" }, "team_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "title", "created_at", "project_id" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "deleteApiV1ChatSessions", "summary": "Delete (archive) all chat sessions", "tags": [ "ai-chat" ], "description": "Archives all of the user's chat sessions.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "project_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted_count" ], "properties": { "deleted_count": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/sessions/{id}": { "get": { "operationId": "getApiV1ChatSessionsById", "summary": "Get chat session with messages", "tags": [ "ai-chat" ], "description": "Returns a single chat session with its full message history.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "user_id", "team_id", "project_id", "title", "created_at", "updated_at", "is_archived", "is_favorite", "briefing_id", "project_type", "ui_messages", "permission", "messages" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "is_archived": { "type": "boolean" }, "is_favorite": { "type": "boolean" }, "briefing_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "project_type": { "type": "string" }, "ui_messages": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "role" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "content": { "type": "string" }, "createdAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "string" }, { "type": "number" }, { "type": "null" } ] } } } }, "permission": { "type": "string" }, "messages": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "role", "content", "data", "credits_used", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "role": { "type": "string" }, "content": { "type": "string" }, "data": { "anyOf": [ { "$comment": "json-value" }, { "type": "null" } ] }, "credits_used": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } }, "patch": { "operationId": "patchApiV1ChatSessionsById", "summary": "Rename chat session", "tags": [ "ai-chat" ], "description": "Updates the title of an existing chat session.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 255, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "format": "uuid", "type": "string" }, "title": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } }, "delete": { "operationId": "deleteApiV1ChatSessionsById", "summary": "Delete (archive) a chat session", "tags": [ "ai-chat" ], "description": "Archives a chat session. The session is soft-deleted and no longer appears in listings.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/unarchive": { "post": { "operationId": "postApiV1ChatSessionsByIdUnarchive", "summary": "Restore an archived chat session", "tags": [ "ai-chat" ], "description": "Moves a previously archived chat session back into the active list.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "is_archived" ], "properties": { "id": { "type": "string" }, "is_archived": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/chat/sessions/{id}/favorite": { "patch": { "operationId": "patchApiV1ChatSessionsByIdFavorite", "summary": "Toggle session favorite", "tags": [ "ai-chat" ], "description": "Toggles the is_favorite flag on a chat session.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "is_favorite" ], "properties": { "id": { "format": "uuid", "type": "string" }, "is_favorite": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/messages/{messageId}/feedback": { "patch": { "operationId": "patchApiV1ChatMessagesByMessageIdFeedback", "summary": "Submit feedback on an assistant message", "tags": [ "ai-chat" ], "description": "Rate an AI response with thumbs up/down and optional comment. The messageId is the client-side UIMessage.id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "rating" ], "properties": { "rating": { "minimum": -1, "maximum": 1, "type": "integer" }, "comment": { "maxLength": 1000, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 200, "type": "string" }, "in": "path", "name": "messageId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/shared-with-me": { "get": { "operationId": "getApiV1ChatSessionsSharedWithMe", "summary": "List sessions shared with the current user", "tags": [ "ai-chat" ], "description": "Returns active standalone AI chat sessions shared with the authenticated user.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "title", "created_at", "updated_at", "permission", "shared_by" ], "properties": { "id": { "format": "uuid", "type": "string" }, "title": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "permission": { "type": "string" }, "shared_by": { "additionalProperties": false, "type": "object", "required": [ "name", "email" ], "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/share": { "post": { "operationId": "postApiV1ChatSessionsByIdShare", "summary": "Share a chat session with a team member", "tags": [ "ai-chat" ], "description": "Grants read or write access to a chat session for another member of the owner team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "user_id", "permission" ], "properties": { "user_id": { "type": "string" }, "permission": { "anyOf": [ { "type": "string", "enum": [ "read" ] }, { "type": "string", "enum": [ "write" ] } ] } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/sessions/{id}/share/{userId}": { "delete": { "operationId": "deleteApiV1ChatSessionsByIdShareByUserId", "summary": "Remove session sharing with a team member", "tags": [ "ai-chat" ], "description": "Revokes a team member share from a chat session owned by the authenticated user.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/actions": { "get": { "operationId": "getApiV1ChatSessionsByIdActions", "summary": "List AI actions for a chat session", "tags": [ "ai-chat" ], "description": "Returns pending and historical AI actions (audit trail) for a chat session.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "chat_message_id", "tool_name", "entity_type", "entity_id", "entity_name", "account_id", "action_params", "status", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "chat_message_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "tool_name": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "action_params": { "$comment": "json-value" }, "status": { "type": "string" }, "result_data": { "anyOf": [ { "$comment": "json-value" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "closed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "executed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "confirmed_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/actions/{actionId}/execute": { "post": { "operationId": "postApiV1ChatSessionsByIdActionsByActionIdExecute", "summary": "Execute a pending AI action", "tags": [ "ai-chat" ], "description": "Confirms and executes a pending AI action with row-level locking and TTL verification.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "actionId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" }, "result_data": { "$comment": "json-value" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "410": { "description": "Gone - resource is permanently removed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "423": { "description": "Response 423", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/actions/{actionId}/reject": { "post": { "operationId": "postApiV1ChatSessionsByIdActionsByActionIdReject", "summary": "Reject a pending AI action", "tags": [ "ai-chat" ], "description": "Marks a pending AI action as rejected.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "actionId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "REJECTED" ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/messages": { "post": { "operationId": "postApiV1ChatSessionsByIdMessages", "summary": "Send message and receive AI response via data stream", "tags": [ "ai-chat" ], "description": "Sends a user message to the AI chat and streams the response back via the AI SDK data stream protocol (`text/event-stream`). The route uses `reply.hijack()` + `pipeUIMessageStreamToResponse()` from the `ai` package, so the declared JSON schemas on other endpoints do NOT apply here. Clients must consume the response as Server-Sent Events and parse each `data:` frame as an AI SDK UIMessage stream chunk. Error responses (400/403/404) are still returned as JSON when the request is rejected before streaming begins.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": { "$comment": "json-value" }, "description": "Chat stream request. Permissive on extra fields so callers can pass provider-specific options without backend changes.", "type": "object", "properties": { "id": { "type": "string" }, "message": { "additionalProperties": { "$comment": "json-value" }, "description": "Single user message. Extra fields (attachments, tool results, provider hints) are forwarded as-is to the AI provider.", "type": "object", "required": [ "id", "role" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } }, "messages": { "maxItems": 100, "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "description": "Conversation history entry. Extra fields are forwarded to the AI provider unchanged.", "type": "object", "required": [ "role" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "content": { "type": "string" } } } }, "trigger": { "type": "string" }, "messageId": { "type": "string" }, "mode": { "maxLength": 16, "type": "string" }, "model": { "type": "string" }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "content": { "maxLength": 5000, "type": "string" }, "page_context": { "additionalProperties": false, "type": "object", "properties": { "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "route_params": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } }, { "type": "null" } ] }, "search_params": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } }, { "type": "null" } ] }, "selected_entity": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "visible_filters": { "anyOf": [ { "type": "object", "additionalProperties": { "$comment": "json-value" } }, { "type": "null" } ] } } } } } } }, "description": "Chat stream request. Permissive on extra fields so callers can pass provider-specific options without backend changes." }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "AI SDK UIMessage data stream served as Server-Sent Events. Each frame is a `data: \\n\\n` line where the payload follows the AI SDK v5 UIMessage stream format (text deltas, tool calls, tool results, finish events, etc.). See the `ai` package (`pipeUIMessageStreamToResponse`) for the payload shape.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Raw SSE frames carrying AI SDK UIMessage stream chunks. Decode with an AI SDK compatible transport on the client." } } } }, "400": { "description": "Request is missing message content or contains an invalid payload.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The user can read the session but cannot send messages to it, or is blocked by abuse controls.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "404": { "description": "Chat session was not found or is not accessible.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat": { "post": { "operationId": "postApiV1Chat", "summary": "Send message and receive AI response via stock AI SDK transport", "tags": [ "ai-chat" ], "description": "Stock AI SDK chat transport: identical streaming semantics to `POST /api/v1/chat/sessions/:id/messages` but the session id is read from the request body. Uses `reply.hijack()` + `pipeUIMessageStreamToResponse()`, so the response is an SSE stream (`text/event-stream`) carrying AI SDK UIMessage chunks, not JSON.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "additionalProperties": { "$comment": "json-value" }, "description": "Chat stream request. Permissive on extra fields so callers can pass provider-specific options without backend changes.", "type": "object", "properties": { "id": { "type": "string" }, "message": { "additionalProperties": { "$comment": "json-value" }, "description": "Single user message. Extra fields (attachments, tool results, provider hints) are forwarded as-is to the AI provider.", "type": "object", "required": [ "id", "role" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } }, "messages": { "maxItems": 100, "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "description": "Conversation history entry. Extra fields are forwarded to the AI provider unchanged.", "type": "object", "required": [ "role" ], "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "parts": { "type": "array", "items": { "additionalProperties": { "$comment": "json-value" }, "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "content": { "type": "string" } } } }, "trigger": { "type": "string" }, "messageId": { "type": "string" }, "mode": { "maxLength": 16, "type": "string" }, "model": { "type": "string" }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "content": { "maxLength": 5000, "type": "string" }, "page_context": { "additionalProperties": false, "type": "object", "properties": { "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "route": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "route_params": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } }, { "type": "null" } ] }, "search_params": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } }, { "type": "null" } ] }, "selected_entity": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "visible_filters": { "anyOf": [ { "type": "object", "additionalProperties": { "$comment": "json-value" } }, { "type": "null" } ] } } } } }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "AI SDK UIMessage data stream served as Server-Sent Events. Each frame is a `data: \\n\\n` line following the AI SDK v5 UIMessage stream format. See `pipeUIMessageStreamToResponse` in the `ai` package for the payload shape.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Raw SSE frames carrying AI SDK UIMessage stream chunks." } } } }, "400": { "description": "Request is missing a chat session id or message content.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The user can read the session but cannot send messages to it, or is blocked by abuse controls.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "404": { "description": "Chat session was not found or is not accessible.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/{id}/stream": { "get": { "operationId": "getApiV1ChatByIdStream", "summary": "Reconnect to an active AI chat stream", "tags": [ "ai-chat" ], "description": "Returns the buffered + live SSE stream for a session. Used by the frontend to resume after refresh/disconnect. The route uses `reply.hijack()` + `reply.raw.writeHead(200, { \"Content-Type\": \"text/event-stream\" })` and pipes bytes from a resumable stream managed by the stream manager (Redis-backed). If there is no active stream the route responds with a plain `204 No Content`; otherwise the response body is a raw SSE payload and the JSON schemas declared elsewhere do NOT apply.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Server-Sent Events stream resumed from the AI SDK UIMessage data stream (same payload shape as `POST /api/v1/chat/sessions/:id/messages`).", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Raw SSE frames carrying AI SDK UIMessage stream chunks replayed from the resumable stream buffer." } } } }, "204": { "description": "No active stream to resume for this session." }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Session not found or not accessible.", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/sessions/{id}/stop": { "post": { "operationId": "postApiV1ChatSessionsByIdStop", "summary": "Stop an active AI chat stream", "tags": [ "ai-chat" ], "description": "Sends a soft stop signal via Redis pub/sub. Works across any pod in a multi-instance cluster.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "stopped" ], "properties": { "stopped": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "stopped" ], "properties": { "stopped": { "type": "boolean" } } } } } } } } }, "/api/v1/chat/models": { "get": { "operationId": "getApiV1ChatModels", "summary": "List the neutral chat capability modes available to the caller", "tags": [ "ai-chat" ], "description": "Returns ONLY opaque capability modes (fast|smart|expert) with per-plan availability. Never exposes the underlying model id, name, provider, version or cost.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "modes" ], "properties": { "modes": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "available", "allowed_by_plan", "available_now", "default" ], "properties": { "key": { "description": "Opaque capability mode: fast | smart | expert.", "type": "string" }, "label": { "description": "Human-readable label for the mode.", "type": "string" }, "available": { "description": "DEPRECATED legacy field, now `allowed_by_plan && available_now` — i.e. the mode is usable. Read allowed_by_plan (upsell) and available_now (temporary unavailability) instead: this single boolean cannot say WHICH of the two failed.", "type": "boolean" }, "allowed_by_plan": { "description": "Whether the caller plan unlocks the mode. false → upsell.", "type": "boolean" }, "available_now": { "description": "Whether the mode can run right now (its lane is configured and not switched off). false → temporary unavailability, not an upgrade prompt.", "type": "boolean" }, "default": { "description": "Whether this is the default mode.", "type": "boolean" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/credits": { "get": { "operationId": "getApiV1ChatCredits", "summary": "Get AI chat credit balance", "tags": [ "ai-chat" ], "description": "Returns the current AI chat credit balance, total purchased, and total used for the team owner.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "grant_balance", "currency", "spendable", "total_purchased", "total_used", "monthly_cap", "monthly_used", "monthly_pct", "monthly_reset_at", "weekly_cap", "weekly_used", "weekly_pct", "weekly_reset_at", "monthly_spend_limit_cents", "monthly_spend_cents", "spend_pct", "spend_reset_at", "auto_recharge" ], "properties": { "balance": { "type": "number" }, "grant_balance": { "type": "number" }, "currency": { "type": "string" }, "spendable": { "type": "number" }, "total_purchased": { "type": "number" }, "total_used": { "type": "number" }, "monthly_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "monthly_used": { "type": "integer" }, "monthly_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthly_reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "weekly_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "weekly_used": { "type": "integer" }, "weekly_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "weekly_reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "monthly_spend_limit_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "monthly_spend_cents": { "type": "integer" }, "spend_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_reset_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "auto_recharge": { "type": "object", "required": [ "enabled", "threshold", "package_key", "target_balance", "monthly_cap_cents", "spent_cents", "last_status" ], "properties": { "enabled": { "type": "boolean" }, "threshold": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "package_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_balance": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "monthly_cap_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "spent_cents": { "type": "integer" }, "last_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/credits/auto-recharge": { "get": { "operationId": "getApiV1ChatCreditsAutoRecharge", "summary": "Get the auto-recharge configuration", "tags": [ "ai-chat" ], "description": "Returns the current auto-recharge threshold, target balance, package, cap, and last status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled", "threshold", "dropToThreshold", "targetBalance", "packageKey", "monthlyCapCents", "spentCents", "lastStatus" ], "properties": { "enabled": { "type": "boolean" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "dropToThreshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "targetBalance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "packageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "monthlyCapCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentCents": { "type": "number" }, "lastStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "putApiV1ChatCreditsAutoRecharge", "summary": "Configure auto-recharge (threshold + package + monthly cap)", "tags": [ "ai-chat" ], "description": "Updates auto-recharge settings used to top up AI credits when balance drops below the threshold.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "threshold": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ] }, "package_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_balance": { "anyOf": [ { "minimum": 1, "maximum": 27777777, "type": "integer" }, { "type": "null" } ] }, "monthly_cap_cents": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled", "threshold", "dropToThreshold", "targetBalance", "packageKey", "monthlyCapCents", "spentCents", "lastStatus" ], "properties": { "enabled": { "type": "boolean" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "dropToThreshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "targetBalance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "packageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "monthlyCapCents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spentCents": { "type": "number" }, "lastStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/credits/history": { "get": { "operationId": "getApiV1ChatCreditsHistory", "summary": "Get credit transaction history", "tags": [ "ai-chat" ], "description": "Returns a paginated list of credit purchase and usage transactions.", "parameters": [ { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "team_id", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "owner_id", "organization_id", "type", "amount", "balance_after", "description", "stripe_payment_intent_id", "chat_message_id", "user_id", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "owner_id": { "format": "uuid", "type": "string" }, "organization_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "amount": { "type": "integer" }, "balance_after": { "type": "integer" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stripe_payment_intent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "chat_message_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "reversal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/credits/packages": { "get": { "operationId": "getApiV1ChatCreditsPackages", "summary": "List purchasable AI credit packages", "tags": [ "ai-chat" ], "description": "Returns the sellable credit top-up packages. Sourced from the credit_package table (enabled + priced) when populated, otherwise the in-code fallback catalogue.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "packages" ], "properties": { "currency": { "type": "string" }, "packages": { "type": "array", "items": { "type": "object", "required": [ "key", "credits", "price_cents", "unit_amount_cents", "currency", "name" ], "properties": { "key": { "type": "string" }, "credits": { "type": "integer" }, "price_cents": { "type": "integer" }, "unit_amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/chat/credits/checkout": { "post": { "operationId": "postApiV1ChatCreditsCheckout", "summary": "Create Stripe checkout for credit purchase", "tags": [ "ai-chat" ], "description": "Creates a Stripe checkout session to purchase an AI chat credit package. Returns the checkout URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "package": { "anyOf": [ { "type": "string", "enum": [ "starter" ] }, { "type": "string", "enum": [ "standard" ] }, { "type": "string", "enum": [ "pro" ] } ] }, "amount_cents": { "minimum": 1, "type": "integer" }, "currency": { "maxLength": 3, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "checkout_url" ], "properties": { "checkout_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error", "limit_cents", "spent_cents" ], "properties": { "error": { "type": "string" }, "limit_cents": { "type": "integer" }, "spent_cents": { "type": "integer" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/credits/purchase": { "post": { "operationId": "postApiV1ChatCreditsPurchase", "summary": "Purchase credits using saved payment method", "tags": [ "ai-chat" ], "description": "Creates a Stripe PaymentIntent to purchase AI chat credits using the customer default payment method. Returns immediately if payment succeeds, or a client_secret for 3D Secure confirmation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "package": { "anyOf": [ { "type": "string", "enum": [ "starter" ] }, { "type": "string", "enum": [ "standard" ] }, { "type": "string", "enum": [ "pro" ] } ] }, "amount_cents": { "minimum": 1, "type": "integer" }, "currency": { "maxLength": 3, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "has_payment_method": { "type": "boolean" }, "setup_client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "success": { "type": "boolean" }, "credits": { "type": "integer" }, "requires_action": { "type": "boolean" }, "client_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "limit_cents": { "type": "integer" }, "spent_cents": { "type": "integer" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/credits/confirm": { "post": { "operationId": "postApiV1ChatCreditsConfirm", "summary": "Confirm 3D Secure credit purchase", "tags": [ "ai-chat" ], "description": "After frontend completes 3D Secure, call this to verify the PaymentIntent succeeded and record credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_intent_id" ], "properties": { "payment_intent_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "success", "credits" ], "properties": { "success": { "type": "boolean" }, "credits": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/preferences": { "get": { "operationId": "getApiV1ChatPreferences", "summary": "Get current user AI preferences", "tags": [ "ai-chat" ], "description": "Returns the current user AI chat preferences with preferred model mapped to a neutral mode.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } }, "put": { "operationId": "putApiV1ChatPreferences", "summary": "Update current user AI preferences", "tags": [ "ai-chat" ], "description": "Updates current user AI chat preferences and persists only neutral model modes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "instructions": { "maxLength": 2000, "type": "string" }, "preferred_language": { "maxLength": 10, "type": "string" }, "preferred_model": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "instructions", "preferred_language", "preferred_model" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expertise_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format_preference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preferred_metrics": { "type": "array", "items": { "type": "string" } }, "preferred_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memory_enabled": { "type": "boolean" }, "memory_opted_out_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/credits/cap": { "put": { "operationId": "putApiV1ChatCreditsCap", "summary": "Update monthly credit cap (owner/admin only)", "tags": [ "ai-chat" ], "description": "Updates the monthly AI credit consumption cap for the billing owner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "monthly_cap" ], "properties": { "monthly_cap": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok", "monthly_cap" ], "properties": { "ok": { "type": "boolean" }, "monthly_cap": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/chat/credits/spend-limit": { "put": { "operationId": "putApiV1ChatCreditsSpendLimit", "summary": "Update monthly spend limit in currency minor units (owner/admin only)", "tags": [ "ai-chat" ], "description": "Updates or removes the monthly spend limit for buying AI credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "monthly_spend_limit_cents" ], "properties": { "monthly_spend_limit_cents": { "anyOf": [ { "minimum": 1, "description": "Positive cap in minor units, or null to remove the limit.", "type": "integer" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ok", "monthly_spend_limit_cents" ], "properties": { "ok": { "type": "boolean" }, "monthly_spend_limit_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" }, "retryAfterSeconds": { "type": "number" } } } } } } } } }, "/api/v1/commerce/attribution-sources": { "get": { "operationId": "getCommerceAttributionSources", "summary": "Revenue and orders grouped by normalized traffic source for the team", "tags": [ "commerce" ], "description": "Aggregates commerce orders in the requested date range by normalized UTM/source bucket (meta, google, email, organic, direct, other), optionally filtered to a connected store.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from", "required": true, "description": "ISO date (inclusive lower bound)" }, { "schema": { "type": "string" }, "in": "query", "name": "to", "required": true, "description": "ISO date (inclusive upper bound)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "catalog_source_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "source", "revenue", "orders" ], "properties": { "source": { "type": "string" }, "revenue": { "type": "number" }, "orders": { "type": "integer" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/orders/{orderId}/attribution": { "patch": { "operationId": "setCommerceOrderAttribution", "summary": "Manually set attribution for a commerce order", "tags": [ "commerce" ], "description": "Creates or updates a manual attribution override for one commerce order. Pass a campaign id to attribute it, or null to mark the order as manually unattributed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "campaign_id" ], "properties": { "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/orders/{orderId}/attribution/revert": { "post": { "operationId": "revertCommerceOrderAttribution", "summary": "Revert manual attribution to automatic", "tags": [ "commerce" ], "description": "Removes the manual attribution override for a commerce order so the automatic attribution worker can evaluate it again on the next run.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "note": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "reverted" ], "properties": { "reverted": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/orders/bulk-attribute": { "post": { "operationId": "bulkSetCommerceOrderAttribution", "summary": "Bulk-set attribution for multiple commerce orders", "tags": [ "commerce" ], "description": "Applies the same manual attribution override to up to 500 commerce orders in the caller team and returns the number updated plus skipped order ids.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "order_ids", "campaign_id" ], "properties": { "order_ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "format": "uuid", "type": "string" } }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated", "skipped" ], "properties": { "updated": { "type": "integer" }, "skipped": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/orders/{orderId}/attribution/history": { "get": { "operationId": "getCommerceOrderAttributionHistory", "summary": "Get manual attribution audit log for a commerce order", "tags": [ "commerce" ], "description": "Returns manual attribution changes for one commerce order, including previous and new campaign values, actor details, timestamp, change type, and optional note.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "changed_at", "change_type", "from_campaign_id", "from_campaign_name", "to_campaign_id", "to_campaign_name", "changed_by_user_id", "changed_by_name", "changed_by_email", "note" ], "properties": { "id": { "type": "string" }, "changed_at": { "type": "string" }, "change_type": { "anyOf": [ { "type": "string", "enum": [ "manual_attribute" ] }, { "type": "string", "enum": [ "manual_reattribute" ] }, { "type": "string", "enum": [ "manual_unattribute" ] }, { "type": "string", "enum": [ "revert_to_auto" ] } ] }, "from_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "from_campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to_campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to_campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changed_by_user_id": { "type": "string" }, "changed_by_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changed_by_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/catalog-priority": { "get": { "operationId": "getApiV1CommerceCatalogPriority", "summary": "List commerce catalog source priority", "tags": [ "commerce" ], "description": "Returns the current source-type ordering used when resolving commerce catalog records for the active team.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ordering" ], "properties": { "ordering": { "type": "array", "items": { "type": "object", "required": [ "priorityRank", "sourceType", "updatedAt" ], "properties": { "priorityRank": { "minimum": 1, "type": "integer" }, "sourceType": { "type": "string" }, "updatedAt": { "type": "string" } } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "apiKeyAuth": [] } ] }, "put": { "operationId": "putApiV1CommerceCatalogPriority", "summary": "Replace commerce catalog source priority", "tags": [ "commerce" ], "description": "Replaces the team-level source-type ordering after validating that ranks and source types are unique.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ordering" ], "properties": { "ordering": { "type": "array", "items": { "type": "object", "required": [ "priorityRank", "sourceType" ], "properties": { "priorityRank": { "minimum": 1, "type": "integer" }, "sourceType": { "minLength": 1, "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/commerce/customers/new": { "get": { "operationId": "getCommerceNewCustomers", "summary": "New customers per day (first-ever order date) for the team", "tags": [ "commerce" ], "description": "Counts customers whose first recorded order falls on each day in the requested range, scoped to the caller team and optionally filtered to one connected store.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from", "required": true, "description": "ISO date (inclusive lower bound)" }, { "schema": { "type": "string" }, "in": "query", "name": "to", "required": true, "description": "ISO date (inclusive upper bound)" }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "catalog_source_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "date", "new_customers" ], "properties": { "date": { "type": "string" }, "new_customers": { "type": "integer" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/match-queue": { "get": { "operationId": "getApiV1CommerceMatchQueue", "summary": "List commerce match review queue", "tags": [ "commerce" ], "description": "Returns pending low-confidence catalog match candidates for the active team, capped by the optional limit.", "parameters": [ { "schema": { "minimum": 1, "maximum": 500, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "autoApproveThreshold" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "candidateExternalId", "candidateSourceId", "confidence", "createdAt", "status", "variantMasterId" ], "properties": { "id": { "type": "string" }, "candidateExternalId": { "type": "string" }, "candidateSourceId": { "type": "string" }, "confidence": { "type": "number" }, "createdAt": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "approved" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "variantMasterId": { "type": "string" } } } }, "autoApproveThreshold": { "type": "number" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/commerce/match-queue/{id}/approve": { "post": { "operationId": "postApiV1CommerceMatchQueueByIdApprove", "summary": "Approve a commerce match candidate", "tags": [ "commerce" ], "description": "Marks one pending catalog match review item as approved for the active team and records the reviewer.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/commerce/match-queue/{id}/reject": { "post": { "operationId": "postApiV1CommerceMatchQueueByIdReject", "summary": "Reject a commerce match candidate", "tags": [ "commerce" ], "description": "Marks one pending catalog match review item as rejected for the active team and records the reviewer.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/commerce/match-queue/bulk-approve": { "post": { "operationId": "postApiV1CommerceMatchQueueBulkApprove", "summary": "Bulk-approve commerce match candidates", "tags": [ "commerce" ], "description": "Approves all pending catalog match review items above the supplied confidence threshold for the active team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "minConfidence": { "minimum": 0, "maximum": 1, "type": "number" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "approvedCount" ], "properties": { "approvedCount": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ] } }, "/api/v1/commerce/revenue/summary": { "get": { "operationId": "getCommerceRevenueSummary", "summary": "Get source-agnostic commerce revenue summary", "tags": [ "commerce" ], "description": "Returns total revenue, profit, orders, spend, ROAS, margin, and related commerce KPIs for the caller team across connected commerce sources.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "catalog_source_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_revenue", "total_sales", "gross_sales", "net_sales", "total_profit", "total_cogs", "total_refunds", "total_orders", "attributed_orders", "unattributed_orders", "attribution_rate_pct", "avg_order_value", "avg_profit_margin_pct", "total_sessions", "total_sessions_added_to_cart", "total_sessions_reached_checkout", "total_sessions_completed_checkout", "currency" ], "properties": { "total_revenue": { "type": "number" }, "total_sales": { "description": "Shopify's Total sales for the period. Null when the store has no collected sales data.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "gross_sales": { "description": "Shopify's Gross sales: product revenue before discounts, returns, tax and shipping. Null when N/A.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_sales": { "description": "Shopify's Net sales: gross sales minus discounts and returns. Null when N/A.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_cogs": { "type": "number" }, "total_refunds": { "type": "number" }, "total_orders": { "type": "number" }, "attributed_orders": { "type": "number" }, "unattributed_orders": { "type": "number" }, "attribution_rate_pct": { "type": "number" }, "avg_order_value": { "type": "number" }, "avg_profit_margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_sessions": { "type": "number" }, "total_sessions_added_to_cart": { "type": "number" }, "total_sessions_reached_checkout": { "type": "number" }, "total_sessions_completed_checkout": { "type": "number" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/revenue/by-campaign": { "get": { "operationId": "getCommerceRevenueByCampaign", "summary": "Get source-agnostic commerce revenue by campaign", "tags": [ "commerce" ], "description": "Returns paginated campaign-level commerce revenue, profit, spend, order, ROAS, and margin metrics for the requested date range with cursor pagination and sorting.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "revenue" ] }, { "type": "string", "enum": [ "profit" ] }, { "type": "string", "enum": [ "spend" ] }, { "type": "string", "enum": [ "orders" ] }, { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "margin" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_dir", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "unattributed", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "revenue", "spend", "roas", "profit", "margin_pct", "orders_count", "units_sold", "high_confidence", "medium_confidence", "low_confidence", "currency", "platform" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "number" }, "spend": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "orders_count": { "type": "number" }, "units_sold": { "type": "number" }, "high_confidence": { "type": "number" }, "medium_confidence": { "type": "number" }, "low_confidence": { "type": "number" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "unattributed": { "type": "object", "required": [ "revenue", "orders_count", "units_sold", "profit" ], "properties": { "revenue": { "type": "number" }, "orders_count": { "type": "number" }, "units_sold": { "type": "number" }, "profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/revenue/trend": { "get": { "operationId": "getCommerceRevenueTrend", "summary": "Get source-agnostic commerce revenue trend", "tags": [ "commerce" ], "description": "Returns revenue/profit trend buckets for the requested date range and granularity, optionally filtered to one connected commerce store.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "day" ] }, { "type": "string", "enum": [ "week" ] }, { "type": "string", "enum": [ "month" ] } ] }, "in": "query", "name": "granularity", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "catalog_source_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "points", "coverage" ], "properties": { "points": { "type": "array", "items": { "type": "object", "required": [ "date", "revenue", "total_sales", "gross_sales", "net_sales", "profit", "cogs", "orders_count", "refunds", "sessions", "margin_pct" ], "properties": { "date": { "type": "string" }, "revenue": { "type": "number" }, "total_sales": { "type": "number" }, "gross_sales": { "type": "number" }, "net_sales": { "type": "number" }, "profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cogs": { "type": "number" }, "orders_count": { "type": "number" }, "refunds": { "type": "number" }, "sessions": { "type": "number" }, "margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "coverage": { "type": "object", "required": [ "full_pct", "partial_pct", "missing_pct" ], "properties": { "full_pct": { "type": "number" }, "partial_pct": { "type": "number" }, "missing_pct": { "type": "number" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/revenue/by-product": { "get": { "operationId": "getCommerceRevenueByProduct", "summary": "Get source-agnostic commerce revenue by product", "tags": [ "commerce" ], "description": "Returns paginated product-level revenue, profit, units, margin, and related commerce metrics for the requested date range, optionally filtered to one store.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "profit" ] }, { "type": "string", "enum": [ "revenue" ] }, { "type": "string", "enum": [ "units" ] }, { "type": "string", "enum": [ "margin" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "catalog_source_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "variant_id", "product_id", "product_title", "variant_title", "sku", "revenue", "cogs", "profit", "margin_pct", "units_sold", "orders_count" ], "properties": { "variant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variant_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "number" }, "cogs": { "type": "number" }, "profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "units_sold": { "type": "number" }, "orders_count": { "type": "number" } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/revenue/product-campaign-matrix": { "get": { "operationId": "getCommerceProductCampaignMatrix", "summary": "Get source-agnostic commerce product/campaign matrix", "tags": [ "commerce" ], "description": "Returns the top product-to-campaign revenue/profit matrix rows for the requested date range so clients can show which campaigns drive each product.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "variant_master_id", "product_title", "variant_title", "sku", "total_revenue", "total_units", "total_profit", "campaigns" ], "properties": { "variant_master_id": { "type": "string" }, "product_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variant_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total_revenue": { "type": "number" }, "total_units": { "type": "number" }, "total_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "campaigns": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "revenue", "units_sold", "spend", "roas" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "number" }, "units_sold": { "type": "number" }, "spend": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "statusCode": { "type": "number" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/orders/{orderId}": { "get": { "operationId": "getStoreOrderDetail", "summary": "Get one order of a connected store with its line items", "tags": [ "commerce" ], "description": "Returns a single order (summary + attribution + UTM) and its line items (product/variant, quantity, unit price, line total) resolved from the order CDM for that store. Responds 404 when the store does not exist in the caller active scope, and when the order does not exist in that store.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "order", "line_items", "refunds", "raw" ], "properties": { "order": { "type": "object", "required": [ "id", "external_order_id", "order_name", "placed_at", "total", "currency", "item_count", "status", "financial_status", "fulfillment_status", "attributed", "campaign", "customer", "discount_codes", "utm_source", "utm_medium", "utm_campaign", "attribution", "profit" ], "properties": { "id": { "type": "string" }, "external_order_id": { "type": "string" }, "order_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "item_count": { "type": "integer" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financial_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributed": { "type": "boolean" }, "campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discount_codes": { "type": "array", "items": { "type": "string" } }, "utm_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm_medium": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm_campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution": { "type": "object", "required": [ "attribution_method", "confidence", "confidence_level", "explanation", "manual_override", "match_status", "matched_entity_id", "matched_entity_name", "matched_entity_platform", "matched_entity_type" ], "properties": { "attribution_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "confidence_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manual_override": { "type": "boolean" }, "match_status": { "type": "string" }, "matched_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "matched_entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "matched_entity_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "matched_entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "profit": { "type": "object", "required": [ "revenue", "cogs", "refund_impact", "shipping", "tax", "gross_profit", "coverage_state", "currency" ], "properties": { "revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cogs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "refund_impact": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shipping": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "gross_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "coverage_state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "external_line_id", "title", "option_label", "sku", "qty", "unit_price", "line_total", "unit_cost", "margin_pct" ], "properties": { "external_line_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "option_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "integer" }, "unit_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "line_total": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit_cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "refunds": { "type": "array", "items": { "type": "object", "required": [ "amount", "reason", "created_at" ], "properties": { "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "raw": { "anyOf": [ { "type": "object", "required": [ "customer_name", "customer_email", "customer_phone", "shipping_method", "shipping_address", "billing_address", "custom_attributes" ], "properties": { "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipping_address": { "type": "array", "items": { "type": "string" } }, "billing_address": { "type": "array", "items": { "type": "string" } }, "custom_attributes": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/orders/export": { "get": { "operationId": "exportStoreOrders", "summary": "Export the filtered orders of one connected store as CSV", "tags": [ "commerce" ], "description": "Returns the orders of a single catalog source as a CSV download, applying the exact same filters, search and sort as GET /commerce/stores/{sourceId}/orders but without pagination. One row per order, mirroring the order-detail panel section by section: summary, customer and shipping, campaign and attribution (score, level, reason), full profit breakdown, refunds, and line items. The repeating parts collapse into one cell each — \"products\" carries product/variant, sku, quantity, unit price, unit cost, margin and line total; \"refunds\" carries date, reason and amount per refund; \"custom_attributes\" carries the order note attributes. CONTAINS PERSONAL DATA: customer name, email, phone and postal addresses are included for Shopify stores with protected customer data access (empty for other stores and for orders synced before that access was granted). Capped at 20k rows, and X-Export-Truncated is set to true when the filtered set is larger. Responds 404 when the store does not exist in the caller active scope.", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "to", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "payment", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "fulfillment", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "shipping", "required": false }, { "schema": { "maxLength": 2000, "type": "string" }, "in": "query", "name": "campaigns", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "attributed" ] }, { "type": "string", "enum": [ "unattributed" ] } ] }, "in": "query", "name": "attribution", "required": false }, { "schema": { "minimum": 0, "type": "number" }, "in": "query", "name": "tmin", "required": false }, { "schema": { "minimum": 0, "type": "number" }, "in": "query", "name": "tmax", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "date" ] }, { "type": "string", "enum": [ "total" ] }, { "type": "string", "enum": [ "profit" ] }, { "type": "string", "enum": [ "order" ] } ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "dir", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/orders": { "get": { "operationId": "getStoreOrders", "summary": "List orders for one connected store (server-side filtered, sorted and paginated)", "tags": [ "commerce" ], "description": "Returns one page of orders for a single catalog source, filtered/sorted server-side, with item quantity, financial/fulfillment status, campaign attribution, gross profit, shipping method and a pseudonymous customer id. KPIs (orders, revenue, AOV, refunds) and filter facets are computed over the whole filtered set, not just the page. Responds 404 when the store does not exist in the caller active scope.", "parameters": [ { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "to", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "payment", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "fulfillment", "required": false }, { "schema": { "maxLength": 500, "type": "string" }, "in": "query", "name": "shipping", "required": false }, { "schema": { "maxLength": 2000, "type": "string" }, "in": "query", "name": "campaigns", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "attributed" ] }, { "type": "string", "enum": [ "unattributed" ] } ] }, "in": "query", "name": "attribution", "required": false }, { "schema": { "minimum": 0, "type": "number" }, "in": "query", "name": "tmin", "required": false }, { "schema": { "minimum": 0, "type": "number" }, "in": "query", "name": "tmax", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "date" ] }, { "type": "string", "enum": [ "total" ] }, { "type": "string", "enum": [ "profit" ] }, { "type": "string", "enum": [ "order" ] } ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "dir", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "kpis", "facets", "page", "has_profit", "orders" ], "properties": { "kpis": { "type": "object", "required": [ "orders", "revenue", "aov", "refunds", "gross_profit" ], "properties": { "orders": { "type": "integer" }, "revenue": { "type": "number" }, "aov": { "type": "number" }, "refunds": { "type": "integer" }, "gross_profit": { "type": "number" } } }, "facets": { "type": "object", "required": [ "payment_statuses", "fulfillment_statuses", "shipping_methods" ], "properties": { "payment_statuses": { "type": "array", "items": { "type": "string" } }, "fulfillment_statuses": { "type": "array", "items": { "type": "string" } }, "shipping_methods": { "type": "array", "items": { "type": "string" } } } }, "page": { "type": "object", "required": [ "limit", "offset", "total", "has_more" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "has_profit": { "type": "boolean" }, "orders": { "type": "array", "items": { "type": "object", "required": [ "external_order_id", "order_name", "placed_at", "total", "currency", "item_count", "status", "financial_status", "fulfillment_status", "attributed", "confidence", "campaign", "campaign_id", "campaign_platform", "customer", "profit", "shipping_method" ], "properties": { "external_order_id": { "type": "string" }, "order_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "item_count": { "type": "integer" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financial_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attributed": { "type": "boolean" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "campaign": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shipping_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/products/{parentExternalId}/provenance": { "get": { "operationId": "getStoreProductProvenance", "summary": "Cross-source provenance for one per-store product", "tags": [ "commerce" ], "description": "Resolves the product variants of a store to their unified variant_master ids and returns the other catalog sources that sell the same master (cross-source provenance), plus whether any master has a pending match-review entry. Responds 404 when the store does not exist in the caller active scope.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "parentExternalId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "master_count", "needs_review", "sources", "collections", "metafields" ], "properties": { "master_count": { "type": "integer" }, "needs_review": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "type", "is_current" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "is_current": { "type": "boolean" } } } }, "collections": { "type": "array", "items": { "type": "string" } }, "metafields": { "type": "array", "items": { "type": "object", "required": [ "namespace", "key", "value" ], "properties": { "namespace": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "key": { "type": "string" }, "value": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/products/{parentExternalId}/campaigns": { "get": { "operationId": "getStoreProductCampaigns", "summary": "Campaigns that advertised one per-store product", "tags": [ "commerce" ], "description": "Resolves the product variants of a store to their unified variant_master ids and returns the campaigns that generated sales for them (aggregated revenue, units, spend and ROAS) from the campaign/product daily stats. Empty until attribution recompute has populated the stats.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "parentExternalId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "items": { "type": "object", "required": [ "campaign_id", "campaign_name", "platform", "revenue", "units_sold", "spend", "roas" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revenue": { "type": "number" }, "units_sold": { "type": "integer" }, "spend": { "type": "number" }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/products": { "get": { "operationId": "getStoreProducts", "summary": "List products (grouped by parent, with variants) for one connected store", "tags": [ "commerce" ], "description": "Returns one page of products for a single catalog source, grouped by parent product and filtered/sorted server-side, each with its variants, plus overview KPIs computed over the whole filtered set. Read from the normalized source-variant CDM for that store. Stock is read in this order: a variant the store marks as not available for sale counts as out of stock whether or not a quantity exists; otherwise, a variant the store keeps no count for (no stock value, or a stock policy of 'untracked') counts as available and stays out of the out_of_stock KPI, even when the connector reports its quantity as 0; otherwise the counted quantity decides.", "parameters": [ { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "maxLength": 40, "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "in" ] }, { "type": "string", "enum": [ "out" ] } ] }, "in": "query", "name": "stock", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "with" ] }, { "type": "string", "enum": [ "missing" ] } ] }, "in": "query", "name": "cost", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "title" ] }, { "type": "string", "enum": [ "price" ] }, { "type": "string", "enum": [ "stock" ] }, { "type": "string", "enum": [ "variants" ] } ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "kpis", "page", "products" ], "properties": { "kpis": { "type": "object", "required": [ "products", "variants", "active", "out_of_stock", "cost_coverage_pct" ], "properties": { "products": { "type": "integer" }, "variants": { "type": "integer" }, "active": { "type": "integer" }, "out_of_stock": { "type": "integer" }, "cost_coverage_pct": { "type": "integer" } } }, "page": { "type": "object", "required": [ "limit", "offset", "total", "has_more" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "products": { "type": "array", "items": { "type": "object", "required": [ "parent_external_id", "title", "status", "category", "description", "vendor", "handle", "images", "tags", "image_url", "currency", "variant_count", "stock_total", "price_min", "price_max", "variants" ], "properties": { "parent_external_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variant_count": { "type": "integer" }, "stock_total": { "type": "integer" }, "price_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "price_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "external_id", "sku", "option_label", "price", "compare_at_price", "cost", "margin_pct", "stock", "availability", "gtin", "barcode", "weight_grams", "image_url" ], "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "option_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "compare_at_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "stock": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "availability": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gtin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "weight_grams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores/{sourceId}/variants/{id}/cost": { "patch": { "operationId": "setStoreVariantCost", "summary": "Set the unit cost (COGS) of one store variant", "tags": [ "commerce" ], "description": "Writes a direct cost amount and currency on a CDM source variant of a connected store, regardless of platform. On Shopify stores it also writes the matching variant-level cost override (the only input the Shopify profit pipeline reads), refreshes the profit snapshots of that variant and re-queues the profit recompute.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "cost_amount", "cost_currency" ], "properties": { "cost_amount": { "minimum": 0, "type": "number" }, "cost_currency": { "minLength": 1, "maxLength": 3, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "clearStoreVariantCost", "summary": "Clear the unit cost (COGS) of one store variant", "tags": [ "commerce" ], "description": "Clears the direct cost amount and currency from a CDM source variant of a connected store, regardless of platform. On Shopify stores it also removes the matching variant-level cost override, refreshes the profit snapshots of that variant and re-queues the profit recompute.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "sourceId", "required": true }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "message" ], "properties": { "id": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/commerce/stores": { "get": { "operationId": "getCommerceStores", "summary": "List the connected commerce stores for the active workspace scope", "tags": [ "commerce" ], "description": "Lists active Shopify and WooCommerce catalog sources connected to the caller active scope with display label, normalized URL, and platform type for store filters.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "stores" ], "properties": { "stores": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "url", "platform", "status", "connected_at", "last_sync_at", "product_count", "order_count", "shopify_config_id", "woocommerce_config_id" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "type": "string" }, "status": { "type": "string" }, "connected_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_count": { "type": "integer" }, "order_count": { "type": "integer" }, "shopify_config_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "woocommerce_config_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/watchlist": { "get": { "operationId": "getApiV1CompetitiveIntelligenceWatchlist", "summary": "List competitor watchlist", "tags": [ "competitive-intelligence" ], "description": "List competitor pages tracked by the current team scope.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "offset", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] }, "in": "query", "name": "is_active", "required": false }, { "schema": { "minLength": 2, "maxLength": 5, "type": "string" }, "in": "query", "name": "country", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "countries", "created_at", "id", "is_active", "name", "search_terms" ], "properties": { "ad_count": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "new_ads_7d": { "type": "number" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "type": "string" }, "team_id": { "type": "string" }, "total_ads": { "type": "number" }, "updated_at": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CompetitiveIntelligenceWatchlist", "summary": "Add competitor to watchlist", "tags": [ "competitive-intelligence" ], "description": "Add a Meta Ad Library page to the competitor watchlist and queue the first sync.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "page_id", "page_name" ], "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "page_id": { "minLength": 1, "type": "string" }, "page_name": { "minLength": 1, "type": "string" }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "anyOf": [ { "type": "string", "enum": [ "daily" ] }, { "type": "string", "enum": [ "weekly" ] } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "countries", "created_at", "id", "is_active", "name", "search_terms" ], "properties": { "ad_count": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "new_ads_7d": { "type": "number" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "type": "string" }, "team_id": { "type": "string" }, "total_ads": { "type": "number" }, "updated_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "current", "error", "max", "message" ], "properties": { "code": { "type": "string" }, "current": { "type": "number" }, "error": { "type": "string", "enum": [ "Payment Required" ] }, "max": { "type": "number" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/watchlist/{id}": { "put": { "operationId": "putApiV1CompetitiveIntelligenceWatchlistById", "summary": "Update competitor watchlist entry", "tags": [ "competitive-intelligence" ], "description": "Update a competitor watchlist entry within the current team scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "page_id": { "type": "string" }, "page_name": { "type": "string" }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "anyOf": [ { "type": "string", "enum": [ "daily" ] }, { "type": "string", "enum": [ "weekly" ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "countries", "created_at", "id", "is_active", "name", "search_terms" ], "properties": { "ad_count": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "new_ads_7d": { "type": "number" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "type": "string" }, "team_id": { "type": "string" }, "total_ads": { "type": "number" }, "updated_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "current", "error", "max", "message" ], "properties": { "code": { "type": "string" }, "current": { "type": "number" }, "error": { "type": "string", "enum": [ "Payment Required" ] }, "max": { "type": "number" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CompetitiveIntelligenceWatchlistById", "summary": "Remove competitor from watchlist", "tags": [ "competitive-intelligence" ], "description": "Soft-delete a competitor watchlist entry.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/watchlist/{id}/sync": { "post": { "operationId": "postApiV1CompetitiveIntelligenceWatchlistByIdSync", "summary": "Queue competitor ad sync", "tags": [ "competitive-intelligence" ], "description": "Queue an asynchronous Meta Ad Library sync for a tracked competitor.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "watchlist_id" ], "properties": { "status": { "type": "string", "enum": [ "queued" ] }, "watchlist_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/suggestions": { "get": { "operationId": "getApiV1CompetitiveIntelligenceSuggestions", "summary": "List competitor suggestions", "tags": [ "competitive-intelligence" ], "description": "List competitor suggestions generated for the current team scope.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "suggested" ] }, { "type": "string", "enum": [ "accepted" ] }, { "type": "string", "enum": [ "dismissed" ] } ] }, "in": "query", "name": "status", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "confidence_score", "created_at", "id", "name", "source", "status" ], "properties": { "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_score": { "type": "number" }, "created_at": { "type": "string" }, "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "$comment": "json-value" }, "id": { "type": "string" }, "name": { "type": "string" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "type": "string" }, "updated_at": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/suggestions/discover": { "post": { "operationId": "postApiV1CompetitiveIntelligenceSuggestionsDiscover", "summary": "Discover competitor suggestions", "tags": [ "competitive-intelligence" ], "description": "Discover competitor suggestions using account context and Meta Ad Library pages.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "status", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "confidence_score", "created_at", "id", "name", "source", "status" ], "properties": { "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_score": { "type": "number" }, "created_at": { "type": "string" }, "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "$comment": "json-value" }, "id": { "type": "string" }, "name": { "type": "string" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "type": "string" }, "updated_at": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "completed" ] }, "total": { "type": "number" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/suggestions/{id}/accept": { "post": { "operationId": "postApiV1CompetitiveIntelligenceSuggestionsByIdAccept", "summary": "Accept competitor suggestion", "tags": [ "competitive-intelligence" ], "description": "Accept a trackable competitor suggestion and add it to the watchlist.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "suggestion", "watchlist" ], "properties": { "suggestion": { "anyOf": [ { "type": "object", "required": [ "confidence_score", "created_at", "id", "name", "source", "status" ], "properties": { "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_score": { "type": "number" }, "created_at": { "type": "string" }, "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "$comment": "json-value" }, "id": { "type": "string" }, "name": { "type": "string" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "type": "string" }, "updated_at": { "type": "string" } } }, { "type": "null" } ] }, "watchlist": { "type": "object", "required": [ "countries", "created_at", "id", "is_active", "name", "search_terms" ], "properties": { "ad_count": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "last_sync_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_sync_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "new_ads_7d": { "type": "number" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "search_terms": { "type": "array", "items": { "type": "string" } }, "sync_frequency": { "type": "string" }, "team_id": { "type": "string" }, "total_ads": { "type": "number" }, "updated_at": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "current", "error", "max", "message" ], "properties": { "code": { "type": "string" }, "current": { "type": "number" }, "error": { "type": "string", "enum": [ "Payment Required" ] }, "max": { "type": "number" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/suggestions/{id}/dismiss": { "patch": { "operationId": "patchApiV1CompetitiveIntelligenceSuggestionsByIdDismiss", "summary": "Dismiss competitor suggestion", "tags": [ "competitive-intelligence" ], "description": "Dismiss a competitor suggestion for the current team scope.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "confidence_score", "created_at", "id", "name", "source", "status" ], "properties": { "accepted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence_score": { "type": "number" }, "created_at": { "type": "string" }, "dismissed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "$comment": "json-value" }, "id": { "type": "string" }, "name": { "type": "string" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "team_id": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/ads": { "get": { "operationId": "getApiV1CompetitiveIntelligenceAds", "summary": "List competitor ads", "tags": [ "competitive-intelligence" ], "description": "List deduplicated competitor ads with optional filters. `destination` splits on-platform ads (Instant Form / Messenger / WhatsApp — the lead-gen proxy) from ads driving to an external site.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "angle", "required": false }, { "schema": { "minLength": 3, "maxLength": 8, "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "external" ] }, { "type": "string", "enum": [ "on_platform" ] } ] }, "in": "query", "name": "destination", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "offset", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to_date", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "watchlist_id", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "first_seen_at", "id" ], "properties": { "ad_bodies": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ad_creation_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_delivery_start_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_delivery_stop_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_descriptions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ad_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_link_captions": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ad_snapshot_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_titles": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "age_gender_breakdown": { "$comment": "json-value" }, "beneficiary_payers": { "$comment": "json-value" }, "competitor_name": { "type": "string" }, "creative_analysis": { "$comment": "json-value" }, "destination_domains": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "destination_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eu_total_reach": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_seen_at": { "type": "string" }, "id": { "type": "string" }, "impressions_lower": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressions_upper": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "media_extraction_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "media_urls": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "meta_ad_id": { "type": "string" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publisher_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "reach_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reach_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reach_summed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spend_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spend_estimate_monthly": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_estimate_monthly_eur": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_lower": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_upper": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "target_ages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "target_gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_locations": { "$comment": "json-value" }, "targeting_uniform": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "team_id": { "type": "string" }, "variant_count": { "type": "number" }, "variant_meta_ad_ids": { "type": "array", "items": { "type": "string" } }, "watchlist_id": { "type": "string" } } } }, "total": { "type": "number" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/alerts": { "get": { "operationId": "getApiV1CompetitiveIntelligenceAlerts", "summary": "List competitor alerts", "tags": [ "competitive-intelligence" ], "description": "List competitive-intelligence alerts for the current team scope.", "parameters": [ { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "unread_only", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "created_at", "id", "title" ], "properties": { "alert_type": { "type": "string" }, "competitor_ad_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "competitor_name": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_read": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value" }, "severity": { "type": "string" }, "snoozed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "type": "string" }, "title": { "type": "string" }, "watchlist_id": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/alerts/{id}/read": { "patch": { "operationId": "patchApiV1CompetitiveIntelligenceAlertsByIdRead", "summary": "Mark competitor alert as read", "tags": [ "competitive-intelligence" ], "description": "Mark a competitive-intelligence alert as read.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "created_at", "id", "title" ], "properties": { "alert_type": { "type": "string" }, "competitor_ad_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "competitor_name": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_read": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value" }, "severity": { "type": "string" }, "snoozed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "type": "string" }, "title": { "type": "string" }, "watchlist_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/alerts/{id}/snooze": { "patch": { "operationId": "patchApiV1CompetitiveIntelligenceAlertsByIdSnooze", "summary": "Snooze competitor alert", "tags": [ "competitive-intelligence" ], "description": "Snooze a competitive-intelligence alert.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "days" ], "properties": { "days": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 7 ] }, { "type": "number", "enum": [ 30 ] } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "created_at", "id", "title" ], "properties": { "alert_type": { "type": "string" }, "competitor_ad_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "competitor_name": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "is_read": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value" }, "severity": { "type": "string" }, "snoozed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "type": "string" }, "title": { "type": "string" }, "watchlist_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/alerts/read-all": { "patch": { "operationId": "patchApiV1CompetitiveIntelligenceAlertsReadAll", "summary": "Mark all competitor alerts as read", "tags": [ "competitive-intelligence" ], "description": "Mark all competitive-intelligence alerts as read for the current team scope.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "number" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/alerts/backfill-notifications": { "post": { "operationId": "postApiV1CompetitiveIntelligenceAlertsBackfillNotifications", "summary": "Backfill competitor alert notifications", "tags": [ "competitive-intelligence" ], "description": "Backfill notifications for existing competitive-intelligence alerts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "team_id": { "format": "uuid", "type": "string" }, "limit": { "minimum": 1, "maximum": 10000, "type": "number" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "alertsScanned", "alertsTouched", "notificationsCreated" ], "properties": { "alertsScanned": { "type": "number" }, "alertsTouched": { "type": "number" }, "notificationsCreated": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/competitive-intelligence/reports/latest": { "get": { "operationId": "getApiV1CompetitiveIntelligenceReportsLatest", "summary": "Get latest competitive report", "tags": [ "competitive-intelligence" ], "description": "Return the latest ready competitive-intelligence report for the current team scope.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "dimension", "id", "period_end", "period_start", "period_type", "team_id" ], "properties": { "content": { "$comment": "json-value" }, "dimension": { "type": "string" }, "generated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "period_type": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "team_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/reports/quota": { "get": { "operationId": "getApiV1CompetitiveIntelligenceReportsQuota", "summary": "Get competitive report daily quota", "tags": [ "competitive-intelligence" ], "description": "Return today's manual report-generation usage for the current team scope (used/limit/remaining).", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "used", "limit", "remaining", "resets_at" ], "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resets_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/correlation": { "get": { "operationId": "getApiV1CompetitiveIntelligenceCorrelation", "summary": "Competitor activity vs own performance correlation", "tags": [ "competitive-intelligence" ], "description": "Correlate the team’s own daily performance with competitor activity (own-account moat).", "parameters": [ { "schema": { "maximum": 90, "minimum": 7, "type": "integer" }, "in": "query", "name": "days", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "insight", "timeline" ], "properties": { "insight": { "anyOf": [ { "type": "null" }, { "type": "object", "required": [ "cpm_correlation", "sample_days" ], "properties": { "cpm_correlation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sample_days": { "type": "number" } } } ] }, "timeline": { "type": "array", "items": { "type": "object", "required": [ "competitor_active_ads", "competitor_new_ads", "competitor_spend_est", "date", "my_cpm", "my_purchases", "my_spend" ], "properties": { "competitor_active_ads": { "type": "number" }, "competitor_new_ads": { "type": "number" }, "competitor_spend_est": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "date": { "type": "string" }, "my_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "my_purchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "my_spend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/velocity": { "get": { "operationId": "getApiV1CompetitiveIntelligenceVelocity", "summary": "Competitor creative velocity", "tags": [ "competitive-intelligence" ], "description": "Creative velocity: which tracked competitors are ramping new ads.", "parameters": [ { "schema": { "maximum": 60, "minimum": 6, "type": "integer" }, "in": "query", "name": "days", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "competitors" ], "properties": { "competitors": { "type": "array", "items": { "type": "object", "required": [ "name", "prior", "recent", "velocity_pct", "watchlist_id" ], "properties": { "name": { "type": "string" }, "prior": { "type": "number" }, "recent": { "type": "number" }, "velocity_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "watchlist_id": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/reports/generate": { "post": { "operationId": "postApiV1CompetitiveIntelligenceReportsGenerate", "summary": "Generate competitive report", "tags": [ "competitive-intelligence" ], "description": "Queue a weekly competitive-intelligence report generation job.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "period_end", "status", "team_id" ], "properties": { "period_end": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "team_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/competitive-intelligence/search-page": { "get": { "operationId": "getApiV1CompetitiveIntelligenceSearchPage", "summary": "Search competitor Meta pages", "tags": [ "competitive-intelligence" ], "description": "Search Meta Ad Library pages to add a trackable competitor. Accepts a page name, a numeric Meta page ID, or a facebook.com URL carrying the page ID; countries scope which ad-delivery markets are searched. Name queries run against Meta full-text search over ad copy — the only page lookup the Ad Library exposes — and results are ranked by how closely the advertiser name matches. An id that resolves to something other than an advertiser Page returns an empty list with reason=not_an_advertiser_page.", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "countries", "required": false }, { "schema": { "minLength": 1, "maxLength": 300, "type": "string" }, "in": "query", "name": "q", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "ad_count", "page_id", "page_name", "source" ], "properties": { "ad_count": { "type": "number" }, "page_id": { "type": "string" }, "page_name": { "type": "string" }, "source": { "type": "string" } } } }, "reason": { "type": "string", "enum": [ "not_an_advertiser_page" ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-ai-register": { "get": { "operationId": "creativeAiRegisterList", "summary": "List the AI-creatives register", "tags": [ "creative-hub", "ai-register" ], "description": "Lists the workspace AI-creatives register required by EU AI Act art. 50(2) traceability: Creative Hub library assets (generated, uploaded, imported) with their AI classification and provenance evidence, the caller's own completed AI generation jobs from the chat and the legacy hub endpoints (media transforms — resize, background removal — and Creatomate composite renders of user footage are not generations and are excluded), and campaign drafts whose ad text was written by a model. `is_ai_generated` is tri-state — NULL means unknown, never human-made. `marking_evidence` says whether the file was actually read or the pipeline merely declared it. Use the /export sibling for the CSV attachment.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 1, "type": "integer" }, "in": "query", "name": "page", "required": false, "description": "1-based page index." }, { "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "integer" }, "in": "query", "name": "page_size", "required": false, "description": "Rows per page." }, { "schema": { "default": "all", "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "ai" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "in": "query", "name": "classified", "required": false, "description": "Classification slice: `ai` = classified as AI-generated, `unknown` = still unclassified assets (chat jobs are excluded, they are AI by construction), `all` = everything." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "total", "page", "page_size" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "entry_type", "kind", "name", "prompt", "url", "result_urls", "provider", "source", "is_ai_generated", "ai_provenance", "marking_evidence", "generation_id", "created_at" ], "properties": { "id": { "description": "Row id: creative_asset.id or creative_job.id.", "type": "string" }, "entry_type": { "description": "Origin table: `asset` = Creative Hub library asset, `generation_job` = completed AI generation job (chat or legacy hub), `campaign_copy` = campaign draft whose ad text was written by a model.", "anyOf": [ { "type": "string", "enum": [ "asset" ] }, { "type": "string", "enum": [ "campaign_copy" ] }, { "type": "string", "enum": [ "generation_job" ] } ] }, "kind": { "description": "Media kind (asset.kind) or generation type (job.type).", "type": "string" }, "name": { "description": "Asset name; always null for generation jobs.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "description": "Generation prompt of a job, truncated to 300 characters. Null for assets.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "description": "Primary media URL.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_urls": { "description": "Every media URL produced by the row.", "type": "array", "items": { "type": "string" } }, "provider": { "description": "AI provider that produced the media.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "description": "Asset source (`generated` | `uploaded` | `imported`), or the job origin: `chat` (AI chat) | `creative_hub` (legacy hub generate endpoints).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_ai_generated": { "description": "AI Act classification. NULL = unknown (no marker found); it never means \"human-made\".", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "ai_provenance": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "marking_evidence": { "description": "Where the classification comes from. `file_bytes` = the stored file was read (marking pipeline, upload detection or backfill) and `ai_provenance` reports what it carried. `pipeline_declaration` = a generation job our pipeline asserts it produced; the delivered file was never re-read, so it is NOT proof the bytes carry the marker. `human_declaration` = manually reclassified by a user. `none` = no evidence recorded.", "anyOf": [ { "type": "string", "enum": [ "file_bytes" ] }, { "type": "string", "enum": [ "pipeline_declaration" ] }, { "type": "string", "enum": [ "human_declaration" ] }, { "type": "string", "enum": [ "none" ] } ] }, "generation_id": { "description": "Wevion generation this asset came from. Non-null rows are immutable AI facts.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "Creation timestamp (ISO 8601).", "type": "string" } } } }, "total": { "description": "Total rows matching the filter across both sources.", "type": "integer" }, "page": { "description": "Requested page (1-based).", "type": "integer" }, "page_size": { "description": "Requested page size.", "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/creative-ai-register/export": { "get": { "operationId": "creativeAiRegisterExport", "summary": "Export the AI-creatives register as CSV", "tags": [ "creative-hub", "ai-register" ], "description": "Same rows as the register list (newest first, up to the newest 5000), as a `text/csv` attachment. Formula-leading cells are prefixed to neutralise spreadsheet formula injection.", "parameters": [ { "schema": { "default": "all", "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "ai" ] }, { "type": "string", "enum": [ "unknown" ] } ] }, "in": "query", "name": "classified", "required": false, "description": "Classification slice: `ai` = classified as AI-generated, `unknown` = still unclassified assets (chat jobs are excluded, they are AI by construction), `all` = everything." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "CSV file content", "content": { "application/json": { "schema": { "description": "CSV file content", "type": "string" } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/creative-ai-register/assets/{assetId}": { "patch": { "operationId": "creativeAiRegisterReclassifyAsset", "summary": "Reclassify an uploaded asset in the AI register", "tags": [ "creative-hub", "ai-register" ], "description": "Manually records whether an uploaded or imported asset is AI-generated, for the cases automatic detection cannot decide (an unmarked upload is stored as unknown). Only rows without a generation_id can be reclassified: an asset produced by a Wevion generation is a recorded fact and answers 409. The change is stamped in `ai_provenance.manual_override`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "is_ai_generated" ], "properties": { "is_ai_generated": { "description": "True when the media is AI-generated, false when it is not.", "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "assetId", "required": true, "description": "creative_asset.id to reclassify." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "is_ai_generated", "ai_provenance" ], "properties": { "id": { "type": "string" }, "is_ai_generated": { "type": "boolean" }, "ai_provenance": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/creative-analytics/gallery": { "get": { "operationId": "getCreativeAnalyticsGallery", "summary": "Creative analytics gallery", "tags": [ "creative-analytics" ], "description": "Per-creative aggregated performance for the date range, with signed thumbnail proxies.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_order", "required": false }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "minimum": 1, "maximum": 48, "default": 24, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "sheet_id", "ad_id", "ad_name", "campaign_id", "campaign_name", "adset_id", "adset_name", "ad_account_id", "ad_account_name", "ad_status", "platform", "account_currency", "creative_thumbnail_url", "creative_thumbnail_proxy", "creative_thumbnail_proxy_large", "first_seen", "last_seen", "spend", "impressions", "clicks", "reach", "purchases", "purchase_value", "leads", "add_to_cart", "conversions", "ctr", "cpc", "cpm", "roas", "cpa", "frequency", "format" ], "properties": { "sheet_id": { "type": "string" }, "ad_id": { "type": "string" }, "ad_name": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "type": "string" }, "adset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adset_name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_account_name": { "type": "string" }, "ad_status": { "type": "string" }, "platform": { "type": "string" }, "account_currency": { "type": "string" }, "creative_thumbnail_url": { "type": "string" }, "creative_thumbnail_proxy": { "type": "string" }, "creative_thumbnail_proxy_large": { "type": "string" }, "first_seen": { "type": "string" }, "last_seen": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "reach": { "type": "number" }, "purchases": { "type": "number" }, "purchase_value": { "type": "number" }, "leads": { "type": "number" }, "add_to_cart": { "type": "number" }, "conversions": { "type": "number" }, "ctr": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "roas": { "type": "number" }, "cpa": { "type": "number" }, "frequency": { "type": "number" }, "format": { "type": "string" } } } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-analytics/fatigue": { "get": { "operationId": "getCreativeFatigueList", "summary": "Creative fatigue scores list", "tags": [ "creative-analytics" ], "description": "Returns paginated creative fatigue scores for accessible ad accounts, including score drivers, thumbnail proxy and sorting filters.", "parameters": [ { "schema": { "minimum": 0, "maximum": 100, "default": 0, "type": "integer" }, "in": "query", "name": "min_score", "required": false }, { "schema": { "type": "array", "items": { "type": "string" } }, "in": "query", "name": "ad_account_ids", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "in": "query", "name": "platform", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "score" ] }, { "type": "string", "enum": [ "avg_frequency" ] }, { "type": "string", "enum": [ "avg_ctr" ] }, { "type": "string", "enum": [ "avg_cpm" ] }, { "type": "string", "enum": [ "impressions" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_order", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "ad_id", "ad_name", "ad_status", "sheet_id", "campaign_id", "campaign_name", "ad_account_id", "platform", "score", "slope_ctr", "avg_frequency", "avg_ctr", "avg_cpm", "avg_cpc", "baseline_ctr", "baseline_cpm", "baseline_cpc", "impressions", "ctr_series", "window_days", "computed_at", "alerted_at", "creative_thumbnail_url", "creative_thumbnail_proxy", "creative_thumbnail_proxy_large" ], "properties": { "ad_id": { "type": "string" }, "ad_name": { "type": "string" }, "ad_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sheet_id": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "integer" }, "slope_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_frequency": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_cpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseline_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseline_cpm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseline_cpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "impressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ctr_series": { "type": "array", "items": { "type": "number" } }, "window_days": { "type": "integer" }, "computed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alerted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creative_thumbnail_url": { "type": "string" }, "creative_thumbnail_proxy": { "type": "string" }, "creative_thumbnail_proxy_large": { "type": "string" } } } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-analytics/fatigue/alert-config": { "get": { "operationId": "getCreativeFatigueAlertConfig", "summary": "Get the per-user Ad Fatigue alert config", "tags": [ "creative-analytics" ], "description": "Returns the email-alert configuration (threshold, recipient, frequency) for the current user.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "email", "email_enabled", "frequency", "threshold" ], "properties": { "email": { "type": "string" }, "email_enabled": { "type": "boolean" }, "frequency": { "anyOf": [ { "type": "string", "enum": [ "immediate" ] }, { "type": "string", "enum": [ "daily" ] }, { "type": "string", "enum": [ "weekly" ] } ] }, "threshold": { "minimum": 1, "maximum": 100, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "operationId": "updateCreativeFatigueAlertConfig", "summary": "Update the per-user Ad Fatigue alert config", "tags": [ "creative-analytics" ], "description": "Persists the email-alert configuration (threshold 1–100, recipient, frequency) for the current user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "email", "email_enabled", "frequency", "threshold" ], "properties": { "email": { "type": "string" }, "email_enabled": { "type": "boolean" }, "frequency": { "anyOf": [ { "type": "string", "enum": [ "immediate" ] }, { "type": "string", "enum": [ "daily" ] }, { "type": "string", "enum": [ "weekly" ] } ] }, "threshold": { "minimum": 1, "maximum": 100, "type": "integer" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "email", "email_enabled", "frequency", "threshold" ], "properties": { "email": { "type": "string" }, "email_enabled": { "type": "boolean" }, "frequency": { "anyOf": [ { "type": "string", "enum": [ "immediate" ] }, { "type": "string", "enum": [ "daily" ] }, { "type": "string", "enum": [ "weekly" ] } ] }, "threshold": { "minimum": 1, "maximum": 100, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-analytics/fatigue/patterns": { "get": { "operationId": "getCreativeFatiguePatterns", "summary": "Historical creative fatigue patterns", "tags": [ "creative-analytics" ], "description": "Aggregates historical fatigue alerts into account-level and percentile timing metrics for accessible ad accounts.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "avg_days_to_fatigue", "p50_days_to_fatigue", "p90_days_to_fatigue", "total_creatives_alerted", "by_account" ], "properties": { "avg_days_to_fatigue": { "type": "number" }, "p50_days_to_fatigue": { "type": "number" }, "p90_days_to_fatigue": { "type": "number" }, "total_creatives_alerted": { "type": "number" }, "by_account": { "type": "array", "items": { "type": "object", "required": [ "ad_account_id", "avg_days", "count" ], "properties": { "ad_account_id": { "type": "string" }, "avg_days": { "type": "number" }, "count": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-analytics/{adId}/fatigue-history": { "get": { "operationId": "getCreativeFatigueHistory", "summary": "Fatigue score history for one ad", "tags": [ "creative-analytics" ], "description": "Returns recent fatigue score snapshots for one ad, optionally scoped to a specific ad account or accessible team member session.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ad_account_id", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sheet_id", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "default": 30, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "ad_id", "ad_account_id", "score", "slope_ctr", "avg_frequency", "avg_ctr", "window_days", "computed_at", "alerted_at" ], "properties": { "id": { "type": "string" }, "ad_id": { "type": "string" }, "ad_account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "integer" }, "slope_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_frequency": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "window_days": { "type": "integer" }, "computed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alerted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-analytics/{adId}/pause": { "post": { "operationId": "pauseCreativeAd", "summary": "Pause a single ad (fatigue tab action)", "tags": [ "creative-analytics" ], "description": "Dispatches a Meta status toggle to PAUSED for the given ad.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ad_account_id" ], "properties": { "ad_account_id": { "type": "string" }, "sheet_id": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "worker_run_id" ], "properties": { "ok": { "type": "boolean" }, "worker_run_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-analytics/{adId}/resume": { "post": { "operationId": "resumeCreativeAd", "summary": "Resume a single ad (fatigue tab action)", "tags": [ "creative-analytics" ], "description": "Dispatches a Meta status toggle to ACTIVE for the given ad.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ad_account_id" ], "properties": { "ad_account_id": { "type": "string" }, "sheet_id": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "adId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "worker_run_id" ], "properties": { "ok": { "type": "boolean" }, "worker_run_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/avatars": { "get": { "operationId": "getApiV1CreativeHubAvatars", "summary": "List Creative Hub avatars", "tags": [ "creative-hub" ], "description": "Returns library and user avatars available for Creative Hub UGC generation flows. The estimated_credits field is the text-to-avatar cost only, kept for backward compatibility: price a specific mode with GET /creative-hub/avatars/estimate.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "scenario", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "gender", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "age_bracket", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "library" ] }, { "type": "string", "enum": [ "mine" ] }, { "type": "string", "enum": [ "all" ] } ] }, "in": "query", "name": "scope", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "estimated_credits" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "gender", "age_bracket", "scenario", "image_url", "thumbnail_url", "preview_video_url", "prompt", "voice_id", "provider", "provider_avatar_ref", "is_library", "status", "tags", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age_bracket": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "provider": { "type": "string" }, "provider_avatar_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_library": { "type": "boolean" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "estimated_credits": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CreativeHubAvatars", "summary": "Create Creative Hub avatar", "tags": [ "creative-hub" ], "description": "Queues a custom text-to-avatar or photo-to-avatar generation job. For mode=text the prompt is composed server-side from `traits`; every group is optional and an unset group falls back to its default.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "mode", "name" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "photo" ] } ] }, "name": { "minLength": 1, "maxLength": 120, "type": "string" }, "prompt": { "maxLength": 2000, "type": "string" }, "traits": { "additionalProperties": false, "description": "Text-to-avatar traits. Every group is optional; the server composes the generation prompt from them.", "type": "object", "properties": { "age": { "anyOf": [ { "type": "string", "enum": [ "teens" ] }, { "type": "string", "enum": [ "twenties" ] }, { "type": "string", "enum": [ "thirties" ] }, { "type": "string", "enum": [ "forties" ] }, { "type": "string", "enum": [ "fifties_plus" ] } ] }, "gender": { "anyOf": [ { "type": "string", "enum": [ "male" ] }, { "type": "string", "enum": [ "female" ] }, { "type": "string", "enum": [ "androgynous" ] }, { "type": "string", "enum": [ "unspecified" ] } ] }, "complexion": { "anyOf": [ { "type": "string", "enum": [ "porcelain" ] }, { "type": "string", "enum": [ "fair" ] }, { "type": "string", "enum": [ "olive" ] }, { "type": "string", "enum": [ "tan" ] }, { "type": "string", "enum": [ "deep" ] } ] }, "hair_color": { "anyOf": [ { "type": "string", "enum": [ "black" ] }, { "type": "string", "enum": [ "brown" ] }, { "type": "string", "enum": [ "blonde" ] }, { "type": "string", "enum": [ "red" ] }, { "type": "string", "enum": [ "grey" ] } ] }, "hair_texture": { "anyOf": [ { "type": "string", "enum": [ "straight" ] }, { "type": "string", "enum": [ "wavy" ] }, { "type": "string", "enum": [ "curly" ] }, { "type": "string", "enum": [ "coily" ] } ] }, "hair_length": { "anyOf": [ { "type": "string", "enum": [ "bald" ] }, { "type": "string", "enum": [ "buzzed" ] }, { "type": "string", "enum": [ "short" ] }, { "type": "string", "enum": [ "medium" ] }, { "type": "string", "enum": [ "long" ] } ] }, "eyes": { "anyOf": [ { "type": "string", "enum": [ "brown" ] }, { "type": "string", "enum": [ "hazel" ] }, { "type": "string", "enum": [ "green" ] }, { "type": "string", "enum": [ "blue" ] }, { "type": "string", "enum": [ "grey" ] } ] }, "makeup": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "natural" ] }, { "type": "string", "enum": [ "defined" ] }, { "type": "string", "enum": [ "bold" ] }, { "type": "string", "enum": [ "dramatic" ] } ] }, "face": { "anyOf": [ { "type": "string", "enum": [ "oval" ] }, { "type": "string", "enum": [ "round" ] }, { "type": "string", "enum": [ "square" ] }, { "type": "string", "enum": [ "heart" ] }, { "type": "string", "enum": [ "angular" ] } ] }, "beard": { "anyOf": [ { "type": "string", "enum": [ "clean" ] }, { "type": "string", "enum": [ "stubble" ] }, { "type": "string", "enum": [ "beard" ] }, { "type": "string", "enum": [ "moustache" ] }, { "type": "string", "enum": [ "goatee" ] } ] }, "marks": { "uniqueItems": true, "maxItems": 5, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "freckles" ] }, { "type": "string", "enum": [ "acne" ] }, { "type": "string", "enum": [ "moles" ] }, { "type": "string", "enum": [ "scars" ] }, { "type": "string", "enum": [ "vitiligo" ] } ] } }, "build": { "anyOf": [ { "type": "string", "enum": [ "slim" ] }, { "type": "string", "enum": [ "average" ] }, { "type": "string", "enum": [ "athletic" ] }, { "type": "string", "enum": [ "muscular" ] }, { "type": "string", "enum": [ "curvy" ] }, { "type": "string", "enum": [ "heavy" ] } ] }, "height": { "anyOf": [ { "type": "string", "enum": [ "petite" ] }, { "type": "string", "enum": [ "short" ] }, { "type": "string", "enum": [ "average" ] }, { "type": "string", "enum": [ "tall" ] }, { "type": "string", "enum": [ "very_tall" ] } ] }, "style_register": { "anyOf": [ { "type": "string", "enum": [ "casual" ] }, { "type": "string", "enum": [ "sporty" ] }, { "type": "string", "enum": [ "formal" ] }, { "type": "string", "enum": [ "streetwear" ] }, { "type": "string", "enum": [ "elegant" ] } ] }, "top": { "anyOf": [ { "type": "string", "enum": [ "tee" ] }, { "type": "string", "enum": [ "shirt" ] }, { "type": "string", "enum": [ "tank" ] }, { "type": "string", "enum": [ "hoodie" ] }, { "type": "string", "enum": [ "sweater" ] }, { "type": "string", "enum": [ "jacket" ] } ] }, "fit": { "anyOf": [ { "type": "string", "enum": [ "slim" ] }, { "type": "string", "enum": [ "regular" ] }, { "type": "string", "enum": [ "relaxed" ] }, { "type": "string", "enum": [ "oversized" ] }, { "type": "string", "enum": [ "boxy" ] } ] }, "material": { "anyOf": [ { "type": "string", "enum": [ "cotton" ] }, { "type": "string", "enum": [ "denim" ] }, { "type": "string", "enum": [ "leather" ] }, { "type": "string", "enum": [ "knit" ] }, { "type": "string", "enum": [ "technical" ] } ] }, "accessories": { "uniqueItems": true, "maxItems": 5, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "glasses" ] }, { "type": "string", "enum": [ "hat" ] }, { "type": "string", "enum": [ "earrings" ] }, { "type": "string", "enum": [ "necklace" ] }, { "type": "string", "enum": [ "none" ] } ] } } } }, "template_avatar_id": { "type": "string" }, "source_image_url": { "type": "string" }, "gender": { "maxLength": 20, "type": "string" }, "age_bracket": { "maxLength": 20, "type": "string" }, "scenario": { "maxLength": 40, "type": "string" }, "voice_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "avatar_id", "generation_id", "status", "estimated_credits", "polling_interval_ms" ], "properties": { "avatar_id": { "format": "uuid", "type": "string" }, "generation_id": { "format": "uuid", "type": "string" }, "status": { "type": "string" }, "estimated_credits": { "minimum": 0, "type": "integer" }, "polling_interval_ms": { "minimum": 1, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/avatars/estimate": { "get": { "operationId": "creativeHubEstimateAvatar", "summary": "Estimate avatar creation credits", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the deterministic credit hold estimate for creating a custom avatar in the requested mode. text prices the photorealistic still generation; photo prices the re-host of the uploaded still. It is the same amount POST /creative-hub/avatars holds and the generation worker settles.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "photo" ] } ] }, "in": "query", "name": "mode", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "mode", "estimated_credits" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "photo" ] } ] }, "estimated_credits": { "minimum": 0, "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/avatars/{id}": { "patch": { "operationId": "patchApiV1CreativeHubAvatarsById", "summary": "Rename Creative Hub avatar", "tags": [ "creative-hub" ], "description": "Renames a custom avatar owned by the authenticated user. Library templates cannot be renamed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 120, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "gender", "age_bracket", "scenario", "image_url", "thumbnail_url", "preview_video_url", "prompt", "voice_id", "provider", "provider_avatar_ref", "is_library", "status", "tags", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age_bracket": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "provider": { "type": "string" }, "provider_avatar_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_library": { "type": "boolean" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CreativeHubAvatarsById", "summary": "Delete Creative Hub avatar", "tags": [ "creative-hub" ], "description": "Soft-deletes a custom avatar owned by the authenticated user.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/avatars/{id}/confirm": { "post": { "operationId": "postApiV1CreativeHubAvatarsByIdConfirm", "summary": "Confirm a generated Creative Hub avatar", "tags": [ "creative-hub" ], "description": "Promotes a generated preview to a saved avatar. Only a preview owned by the authenticated user can be confirmed.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "gender", "age_bracket", "scenario", "image_url", "thumbnail_url", "preview_video_url", "prompt", "voice_id", "provider", "provider_avatar_ref", "is_library", "status", "tags", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age_bracket": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scenario": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_video_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "provider": { "type": "string" }, "provider_avatar_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_library": { "type": "boolean" }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/avatars/{id}/regenerate": { "post": { "operationId": "postApiV1CreativeHubAvatarsByIdRegenerate", "summary": "Regenerate a Creative Hub avatar preview", "tags": [ "creative-hub" ], "description": "Runs the generation again on the traits already stored for the preview. An optional feedback note is appended to the previous free text instead of replacing it. Charges the generation again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "feedback": { "maxLength": 2000, "type": "string" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "avatar_id", "estimated_credits", "generation_id", "polling_interval_ms", "status" ], "properties": { "avatar_id": { "format": "uuid", "type": "string" }, "estimated_credits": { "minimum": 0, "type": "integer" }, "generation_id": { "format": "uuid", "type": "string" }, "polling_interval_ms": { "minimum": 0, "type": "integer" }, "status": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/brand-kits": { "get": { "operationId": "getApiV1CreativeHubBrandKits", "summary": "List Creative Hub brand kits", "tags": [ "creative-hub" ], "description": "Returns brand kits of the active workspace scope team for Creative Hub generation flows.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "website", "logo_url", "colors", "fonts", "tagline", "description", "tone", "source", "is_default", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "type": "string" } }, "fonts": { "type": "array", "items": { "type": "string" } }, "tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "is_default": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CreativeHubBrandKits", "summary": "Create Creative Hub brand kit", "tags": [ "creative-hub" ], "description": "Creates a brand kit for the active workspace scope team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "website": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "maxLength": 16, "type": "string" } }, "fonts": { "type": "array", "items": { "maxLength": 60, "type": "string" } }, "tagline": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "url" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "is_default": { "type": "boolean" }, "metadata": { "additionalProperties": false, "type": "object", "properties": { "business_model": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ] }, "industry": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ] }, "socials": { "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "platform", "url" ], "properties": { "platform": { "maxLength": 40, "type": "string" }, "url": { "maxLength": 500, "type": "string" } } } }, "languages": { "maxItems": 30, "type": "array", "items": { "maxLength": 60, "type": "string" } }, "visual_style": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ] }, "keywords": { "maxItems": 50, "type": "array", "items": { "maxLength": 80, "type": "string" } }, "words_to_avoid": { "maxItems": 50, "type": "array", "items": { "maxLength": 80, "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "website", "logo_url", "colors", "fonts", "tagline", "description", "tone", "source", "is_default", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "type": "string" } }, "fonts": { "type": "array", "items": { "type": "string" } }, "tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "is_default": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/brand-kits/{id}": { "patch": { "operationId": "patchApiV1CreativeHubBrandKitsById", "summary": "Update Creative Hub brand kit", "tags": [ "creative-hub" ], "description": "Updates a brand kit for the active workspace scope team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "website": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "maxLength": 16, "type": "string" } }, "fonts": { "type": "array", "items": { "maxLength": 60, "type": "string" } }, "tagline": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "url" ] }, { "type": "string", "enum": [ "manual" ] } ] }, "is_default": { "type": "boolean" }, "metadata": { "additionalProperties": false, "type": "object", "properties": { "business_model": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ] }, "industry": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ] }, "socials": { "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "platform", "url" ], "properties": { "platform": { "maxLength": 40, "type": "string" }, "url": { "maxLength": 500, "type": "string" } } } }, "languages": { "maxItems": 30, "type": "array", "items": { "maxLength": 60, "type": "string" } }, "visual_style": { "anyOf": [ { "maxLength": 2000, "type": "string" }, { "type": "null" } ] }, "keywords": { "maxItems": 50, "type": "array", "items": { "maxLength": 80, "type": "string" } }, "words_to_avoid": { "maxItems": 50, "type": "array", "items": { "maxLength": 80, "type": "string" } } } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "website", "logo_url", "colors", "fonts", "tagline", "description", "tone", "source", "is_default", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "type": "string" } }, "fonts": { "type": "array", "items": { "type": "string" } }, "tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "is_default": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CreativeHubBrandKitsById", "summary": "Delete Creative Hub brand kit", "tags": [ "creative-hub" ], "description": "Soft-deletes a brand kit for the active workspace scope team.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/brand-kits/import": { "post": { "operationId": "postApiV1CreativeHubBrandKitsImport", "summary": "Preview brand kit import", "tags": [ "creative-hub" ], "description": "Scrapes a website and returns a non-persisted brand kit preview for user confirmation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 4, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "business_model", "colors", "description", "fonts", "industry", "keywords", "languages", "logo_url", "name", "tagline", "tone", "visual_style", "website" ], "properties": { "business_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "colors": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fonts": { "type": "array", "items": { "type": "string" } }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visual_style": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/explore": { "get": { "operationId": "creativeHubListExplore", "summary": "List curated Creative Hub inspiration items", "tags": [ "creative-hub" ], "description": "Returns the curated Creative Hub explore catalog and category list, optionally filtered by category for recreate-this inspiration flows.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "category", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "categories", "items" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "description", "thumbnail_url", "category", "target", "prompt" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "thumbnail_url": { "type": "string" }, "category": { "type": "string" }, "target": { "anyOf": [ { "type": "string", "enum": [ "ugc" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, "prompt": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/team-folders": { "get": { "operationId": "getApiV1CreativeHubTeamFolders", "summary": "List team member folders visible to current user based on role", "tags": [ "creative-hub" ], "description": "Returns the cached Drive root for every visible team member. This is a read-only inventory: members without a provisioned root are returned with folder_id=null and status 'needs_provisioning'; the listing never creates Drive folders nor mutates app_settings.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "folders" ], "properties": { "folders": { "type": "array", "items": { "type": "object", "required": [ "session_id", "user_id", "name", "email", "role", "folder_id", "status" ], "properties": { "session_id": { "type": "string" }, "user_id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "role": { "type": "string" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "ready" ] }, { "type": "string", "enum": [ "needs_provisioning" ] } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/team-folders/provision": { "post": { "operationId": "postApiV1CreativeHubTeamFoldersProvision", "summary": "Provision a Drive root for the caller or a visible team member", "tags": [ "creative-hub" ], "description": "Idempotently creates the Drive root for the target user (default: the caller) under a per-(team, user) lock. The target must be within the caller team-scoped visible set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "sessionId": { "minLength": 1, "maxLength": 128, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "user_id", "folder_id", "status" ], "properties": { "session_id": { "type": "string" }, "user_id": { "type": "string" }, "folder_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/files": { "get": { "operationId": "getApiV1CreativeHubFiles", "summary": "List files and folders", "tags": [ "creative-hub" ], "description": "Lists files and folders from Google Drive for the current user or a specified team member.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "folderId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "memberId", "required": false, "description": "View files of a specific team member (admin/owner/super_admin only)" }, { "schema": { "type": "string" }, "in": "query", "name": "pageToken", "required": false }, { "schema": { "minimum": 1, "maximum": 1000, "default": 100, "type": "number" }, "in": "query", "name": "pageSize", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "files", "nextPageToken", "userFolderId", "currentFolderId", "member" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "mimeType", "size", "createdTime", "modifiedTime", "thumbnailUrl", "contentUrl", "viewUrl", "downloadUrl", "isVideo", "isImage", "isAudio", "isFolder", "parents" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" }, "createdTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVideo": { "type": "boolean" }, "isImage": { "type": "boolean" }, "isAudio": { "type": "boolean" }, "isFolder": { "type": "boolean" }, "parents": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } } }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userFolderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currentFolderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "member": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email", "role" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "role": { "type": "string" } } }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/breadcrumb": { "get": { "operationId": "getApiV1CreativeHubBreadcrumb", "summary": "Get folder breadcrumb path", "tags": [ "creative-hub" ], "description": "Resolves the parent chain from a folder up to the user root to build a breadcrumb navigation path.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "folderId", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "memberId", "required": false, "description": "The team member whose folder tree to resolve" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "breadcrumb" ], "properties": { "breadcrumb": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/upload": { "post": { "operationId": "postApiV1CreativeHubUpload", "summary": "Upload files to Drive", "tags": [ "creative-hub" ], "description": "Uploads one or more files to the user's Google Drive folder via multipart form data. Supports up to 50 files, 500MB each.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "uploaded", "count" ], "properties": { "uploaded": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "id", "name", "mimeType", "size", "createdTime", "modifiedTime", "thumbnailUrl", "contentUrl", "viewUrl", "downloadUrl", "isVideo", "isImage", "isAudio", "isFolder", "parents" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" }, "createdTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVideo": { "type": "boolean" }, "isImage": { "type": "boolean" }, "isAudio": { "type": "boolean" }, "isFolder": { "type": "boolean" }, "parents": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } }, { "type": "object", "required": [ "error" ], "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "type": "string" } } } ] } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "folderId": { "type": "string", "description": "Optional target Drive folder id." }, "file": { "type": "string", "format": "binary", "description": "One or more uploaded files." } }, "additionalProperties": true } } } } } }, "/api/v1/creative-hub/import-url": { "post": { "operationId": "postApiV1CreativeHubImportUrl", "summary": "Import generated chat media into Creative Hub", "tags": [ "creative-hub" ], "description": "Server-side imports an AI Chat generated image/video from the configured creative media CDN or S3 bucket into the current user Drive folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 1, "maxLength": 2048, "type": "string" }, "filename": { "minLength": 1, "maxLength": 180, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "object", "required": [ "id", "name", "mimeType", "size", "createdTime", "modifiedTime", "thumbnailUrl", "contentUrl", "viewUrl", "downloadUrl", "isVideo", "isImage", "isAudio", "isFolder", "parents" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" }, "createdTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVideo": { "type": "boolean" }, "isImage": { "type": "boolean" }, "isAudio": { "type": "boolean" }, "isFolder": { "type": "boolean" }, "parents": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Response 415", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/download-url": { "post": { "operationId": "postApiV1CreativeHubDownloadUrl", "summary": "Download generated chat media", "tags": [ "creative-hub" ], "description": "Server-side downloads an AI Chat generated image/video from the configured creative media CDN or S3 bucket so browsers can save it as a file instead of opening a cross-origin tab.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 1, "maxLength": 2048, "type": "string" }, "filename": { "minLength": 1, "maxLength": 180, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Generated media file stream. Content-Type is the original image/* or video/* media type.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } }, "video/*": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Response 415", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/delete": { "post": { "operationId": "postApiV1CreativeHubDelete", "summary": "Delete files or folders", "tags": [ "creative-hub" ], "description": "Moves files or folders to trash on Google Drive. Falls back to permanent delete if trash fails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fileIds" ], "properties": { "fileIds": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "deleted" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "id", "success" ], "properties": { "id": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } }, "deleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/folder": { "post": { "operationId": "postApiV1CreativeHubFolder", "summary": "Create a new folder", "tags": [ "creative-hub" ], "description": "Creates a new folder in the user's Google Drive space, optionally under a specific parent folder.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "type": "string" }, "parentFolderId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "folder" ], "properties": { "folder": { "type": "object", "required": [ "id", "name", "mimeType", "size", "createdTime", "modifiedTime", "thumbnailUrl", "contentUrl", "viewUrl", "downloadUrl", "isVideo", "isImage", "isAudio", "isFolder", "parents" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" }, "createdTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVideo": { "type": "boolean" }, "isImage": { "type": "boolean" }, "isAudio": { "type": "boolean" }, "isFolder": { "type": "boolean" }, "parents": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/rename": { "patch": { "operationId": "patchApiV1CreativeHubRename", "summary": "Rename a file or folder", "tags": [ "creative-hub" ], "description": "Renames a single file or folder on Google Drive.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fileId", "newName" ], "properties": { "fileId": { "type": "string" }, "newName": { "minLength": 1, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "object", "required": [ "id", "name", "mimeType" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/bulk-rename": { "post": { "operationId": "postApiV1CreativeHubBulkRename", "summary": "Bulk rename files", "tags": [ "creative-hub" ], "description": "Renames multiple files or folders in a single request. Returns individual success/failure results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "minItems": 1, "type": "array", "items": { "type": "object", "required": [ "fileId", "newName" ], "properties": { "fileId": { "type": "string" }, "newName": { "minLength": 1, "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "renamed" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "fileId", "newName", "success" ], "properties": { "fileId": { "type": "string" }, "newName": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } }, "renamed": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/move": { "post": { "operationId": "postApiV1CreativeHubMove", "summary": "Move files to a different folder", "tags": [ "creative-hub" ], "description": "Moves one or more files to a target folder on Google Drive (drag and drop support).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fileIds", "targetFolderId" ], "properties": { "fileIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "targetFolderId": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "results", "moved" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "id", "success" ], "properties": { "id": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } } } }, "moved": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/files/{fileId}/url": { "get": { "operationId": "getApiV1CreativeHubFilesByFileIdUrl", "summary": "Get direct URL for a creative file", "tags": [ "creative-hub" ], "description": "Returns the direct download URL and metadata for a file on Google Drive.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "directUrl" ], "properties": { "url": { "type": "string" }, "directUrl": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/media-capabilities": { "post": { "operationId": "postApiV1CreativeHubMediaCapabilities", "summary": "Mint signed media capability tokens for Drive files", "tags": [ "creative-hub" ], "description": "Returns short-lived, fileId-bound capability tokens for the requested Drive files that live within the caller tenant-allowed Drive roots (own folder + visible team members). The tokens gate the unauthenticated thumbnail/content proxies so the browser can load media without a Bearer header. Files outside the allowed roots are omitted (never minted). Used to (re)mint caps at render time — e.g. for stored campaign drafts — so capability URLs are never persisted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fileIds" ], "properties": { "fileIds": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "capabilities" ], "properties": { "capabilities": { "type": "array", "items": { "type": "object", "required": [ "fileId", "cap", "exp" ], "properties": { "fileId": { "type": "string" }, "cap": { "type": "string" }, "exp": { "type": "integer" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/video": { "post": { "operationId": "creativeHubGenerateVideo", "summary": "Generate an AI video clip", "tags": [ "creative-hub", "creative-generation" ], "description": "Queues an AI video generation job using Luma or Runway. Returns 202 Accepted with an async-job handle; poll GET /api/v1/creative-hub/generate/jobs/:id to retrieve the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "minLength": 1, "maxLength": 2000, "type": "string" }, "image_url": { "type": "string" }, "duration": { "minimum": 2, "maximum": 10, "type": "integer" }, "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "luma_ray3" ] }, { "type": "string", "enum": [ "runway_gen4" ] } ] }, "drive_folder_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "polling_interval_ms", "created_at" ], "properties": { "job_id": { "description": "ID of the queued creative_job row", "type": "string" }, "status": { "description": "Initial job status (always \"pending\" right after enqueue)", "type": "string" }, "polling_interval_ms": { "description": "Suggested polling interval for GET /generate/jobs/:id", "type": "integer" }, "estimated_wait_ms": { "description": "Rough estimated completion wait (provider-dependent)", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/image": { "post": { "operationId": "creativeHubGenerateImage", "summary": "Generate an AI image from a text prompt", "tags": [ "creative-hub", "creative-generation" ], "description": "Queues an AI image generation job (Flux 2 Pro with GPT-Image fallback). Returns 202 Accepted with an async-job handle; poll GET /api/v1/creative-hub/generate/jobs/:id to retrieve the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "minLength": 1, "maxLength": 2000, "type": "string" }, "width": { "minimum": 256, "maximum": 2048, "type": "integer" }, "height": { "minimum": 256, "maximum": 2048, "type": "integer" }, "num_variants": { "minimum": 1, "maximum": 4, "type": "integer" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "flux_2_pro" ] }, { "type": "string", "enum": [ "gpt_image_1_5" ] } ] }, "drive_folder_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "polling_interval_ms", "created_at" ], "properties": { "job_id": { "description": "ID of the queued creative_job row", "type": "string" }, "status": { "description": "Initial job status (always \"pending\" right after enqueue)", "type": "string" }, "polling_interval_ms": { "description": "Suggested polling interval for GET /generate/jobs/:id", "type": "integer" }, "estimated_wait_ms": { "description": "Rough estimated completion wait (provider-dependent)", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/avatar": { "post": { "operationId": "creativeHubGenerateAvatar", "summary": "Generate an avatar UGC video with HeyGen", "tags": [ "creative-hub", "creative-generation" ], "description": "Queues an avatar-based UGC video generation job via HeyGen. Returns 202 Accepted with an async-job handle; poll GET /api/v1/creative-hub/generate/jobs/:id to retrieve the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "script" ], "properties": { "script": { "minLength": 1, "maxLength": 5000, "type": "string" }, "avatar_id": { "type": "string" }, "voice_id": { "type": "string" }, "language": { "type": "string" }, "drive_folder_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "polling_interval_ms", "created_at" ], "properties": { "job_id": { "description": "ID of the queued creative_job row", "type": "string" }, "status": { "description": "Initial job status (always \"pending\" right after enqueue)", "type": "string" }, "polling_interval_ms": { "description": "Suggested polling interval for GET /generate/jobs/:id", "type": "integer" }, "estimated_wait_ms": { "description": "Rough estimated completion wait (provider-dependent)", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/tts": { "post": { "operationId": "creativeHubGenerateTTS", "summary": "Generate text-to-speech audio", "tags": [ "creative-hub", "creative-generation" ], "description": "Queues a TTS audio generation job via ElevenLabs or OpenAI. Returns 202 Accepted with an async-job handle; poll GET /api/v1/creative-hub/generate/jobs/:id to retrieve the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "minLength": 1, "maxLength": 5000, "type": "string" }, "voice_id": { "type": "string" }, "language": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "elevenlabs" ] }, { "type": "string", "enum": [ "openai_tts" ] } ] }, "drive_folder_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "polling_interval_ms", "created_at" ], "properties": { "job_id": { "description": "ID of the queued creative_job row", "type": "string" }, "status": { "description": "Initial job status (always \"pending\" right after enqueue)", "type": "string" }, "polling_interval_ms": { "description": "Suggested polling interval for GET /generate/jobs/:id", "type": "integer" }, "estimated_wait_ms": { "description": "Rough estimated completion wait (provider-dependent)", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/composite": { "post": { "operationId": "creativeHubGenerateComposite", "summary": "Assemble a composite video with Creatomate", "tags": [ "creative-hub", "creative-generation" ], "description": "Queues a composite video assembly job via Creatomate with multiple media elements. Returns 202 Accepted with an async-job handle; poll GET /api/v1/creative-hub/generate/jobs/:id to retrieve the result.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "elements" ], "properties": { "template_id": { "type": "string" }, "elements": { "type": "array", "items": { "type": "object", "required": [ "type", "source" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "audio" ] }, { "type": "string", "enum": [ "text" ] } ] }, "source": { "type": "string" }, "start_time": { "type": "number" }, "duration": { "type": "number" }, "position": { "type": "object", "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } } }, "style": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } }, "width": { "type": "integer" }, "height": { "type": "integer" }, "duration": { "type": "number" }, "drive_folder_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "polling_interval_ms", "created_at" ], "properties": { "job_id": { "description": "ID of the queued creative_job row", "type": "string" }, "status": { "description": "Initial job status (always \"pending\" right after enqueue)", "type": "string" }, "polling_interval_ms": { "description": "Suggested polling interval for GET /generate/jobs/:id", "type": "integer" }, "estimated_wait_ms": { "description": "Rough estimated completion wait (provider-dependent)", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/jobs": { "get": { "operationId": "creativeHubListGenerationJobs", "summary": "List creative generation jobs", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns a paginated list of the current user's creative generation jobs, with optional type and status filters. Uses cursor-based pagination (next_cursor is the id of the last item).", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "avatar" ] }, { "type": "string", "enum": [ "tts" ] }, { "type": "string", "enum": [ "composite" ] } ] }, "in": "query", "name": "type", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "minimum": 1, "maximum": 50, "default": 20, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "status", "provider", "prompt", "result_urls", "cost_cents", "error_message", "created_at", "completed_at" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_urls": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "cost_cents": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/generate/jobs/{id}": { "get": { "operationId": "creativeHubGetGenerationJob", "summary": "Get creative generation job status", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the full details and current status of a specific creative generation job.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "type", "status", "provider", "prompt", "settings", "result_urls", "error_message", "cost_cents", "drive_folder_id", "metadata", "created_at", "completed_at" ], "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": "string" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "result_urls": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cost_cents": { "type": "integer" }, "drive_folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generate/avatars": { "get": { "operationId": "creativeHubListAvatars", "summary": "List available HeyGen avatars", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the list of available HeyGen avatars that can be used for UGC video generation. The avatar shape is provider-defined (HeyGen) and may evolve - treated as an opaque object map.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "avatars" ], "properties": { "avatars": { "type": "array", "items": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/image-creatives/generate": { "post": { "operationId": "creativeHubGenerateImageCreative", "summary": "Generate static ad image creatives (async)", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous static ad creative generation. When brand_kit_id or product_id is provided, the selected team brand or product context is folded into the provider prompt. Up to 4 reference images can be supplied via reference_image_urls; product_image_url stays accepted as the first reference for back-compat. Supplying any reference switches the model from text-to-image (Seedream 4.5) to the reference-preserving Nano Banana Pro and is priced at that higher rate. brand_colors fold into the prompt as colour art direction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "objective" ], "properties": { "objective": { "anyOf": [ { "type": "string", "enum": [ "sales" ] }, { "type": "string", "enum": [ "awareness" ] }, { "type": "string", "enum": [ "traffic" ] }, { "type": "string", "enum": [ "leads" ] } ] }, "product_id": { "minLength": 1, "maxLength": 100, "type": "string" }, "product_description": { "maxLength": 2000, "type": "string" }, "product_image_url": { "type": "string" }, "reference_image_urls": { "maxItems": 4, "type": "array", "items": { "maxLength": 2000, "type": "string" } }, "format": { "anyOf": [ { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "3:4" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "16:9" ] } ] }, "language": { "type": "string" }, "style": { "maxLength": 64, "type": "string" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "num_variants": { "minimum": 1, "maximum": 4, "type": "integer" }, "brand_colors": { "maxItems": 5, "type": "array", "items": { "type": "string" } }, "brand_kit_id": { "minLength": 1, "maxLength": 100, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "created_at", "credits_estimated", "generation_id", "polling_interval_ms", "status" ], "properties": { "created_at": { "type": "string" }, "credits_estimated": { "type": "integer" }, "generation_id": { "type": "string" }, "polling_interval_ms": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/image-creatives/estimate": { "post": { "operationId": "creativeHubEstimateImageCreative", "summary": "Estimate image creative generation credit cost", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the deterministic credit hold estimate for an image creative generation. Supplying any reference image (reference_image_urls or product_image_url) raises the estimate to the reference-preserving model rate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "num_variants" ], "properties": { "num_variants": { "minimum": 1, "maximum": 4, "type": "integer" }, "product_image_url": { "type": "string" }, "reference_image_urls": { "maxItems": 4, "type": "array", "items": { "maxLength": 2000, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/image-creatives/generations": { "get": { "operationId": "creativeHubListImageCreativeGenerations", "summary": "List image creative generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Lists image creative generations for the authenticated user and joins completed assets.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "batch_id", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generations", "next_cursor" ], "properties": { "generations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "assets", "batch_id", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "mode", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "format", "id", "kind", "name", "thumbnail_url", "url" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } } }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "billing": { "additionalProperties": false, "type": "object", "properties": { "ai_chat_credits_actual": { "type": "number" }, "ai_chat_credits_estimated": { "type": "number" }, "higgsfield_credits_actual": { "type": "number" }, "higgsfield_credits_estimated": { "type": "number" }, "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "model_id", "provider", "provider_cents_per_unit", "provider_cost_cents_estimated", "retail_credits", "retail_credits_per_unit", "unit", "units" ], "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "provider_cents_per_unit": { "type": "number" }, "provider_cost_cents_estimated": { "type": "number" }, "retail_credits": { "type": "number" }, "retail_credits_per_unit": { "type": "number" }, "unit": { "type": "string" }, "units": { "type": "number" } } } }, "model_id": { "type": "string" }, "model_unit": { "type": "string" }, "model_units_actual": { "type": "number" }, "model_units_estimated": { "type": "number" }, "pricing_version": { "type": "string" }, "provider": { "type": "string" }, "provider_cents_per_unit": { "type": "number" }, "provider_cost_cents_actual": { "type": "number" }, "provider_cost_cents_estimated": { "type": "number" }, "provider_credits_actual": { "type": "number" }, "provider_credits_estimated": { "type": "number" }, "retail_credits_per_higgsfield_credit": { "type": "number" }, "retail_credits_per_unit": { "type": "number" }, "retail_credits_per_variant": { "type": "number" }, "total_credits_charged": { "type": "number" }, "total_credits_estimated": { "type": "number" } } }, "brand_kit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_kit_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimated_cost_cents": { "type": "number" }, "format": { "anyOf": [ { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "3:4" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "16:9" ] } ] }, "frame_prompt": { "type": "string" }, "language": { "type": "string" }, "num_variants": { "type": "integer" }, "objective": { "anyOf": [ { "type": "string", "enum": [ "sales" ] }, { "type": "string", "enum": [ "awareness" ] }, { "type": "string", "enum": [ "traffic" ] }, { "type": "string", "enum": [ "leads" ] } ] }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/image-creatives/generations/{id}": { "get": { "operationId": "creativeHubGetImageCreativeGeneration", "summary": "Get image creative generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns one image creative generation for polling/detail views.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "assets", "batch_id", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "mode", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "format", "id", "kind", "name", "thumbnail_url", "url" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } } }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "billing": { "additionalProperties": false, "type": "object", "properties": { "ai_chat_credits_actual": { "type": "number" }, "ai_chat_credits_estimated": { "type": "number" }, "higgsfield_credits_actual": { "type": "number" }, "higgsfield_credits_estimated": { "type": "number" }, "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "model_id", "provider", "provider_cents_per_unit", "provider_cost_cents_estimated", "retail_credits", "retail_credits_per_unit", "unit", "units" ], "properties": { "model_id": { "type": "string" }, "provider": { "type": "string" }, "provider_cents_per_unit": { "type": "number" }, "provider_cost_cents_estimated": { "type": "number" }, "retail_credits": { "type": "number" }, "retail_credits_per_unit": { "type": "number" }, "unit": { "type": "string" }, "units": { "type": "number" } } } }, "model_id": { "type": "string" }, "model_unit": { "type": "string" }, "model_units_actual": { "type": "number" }, "model_units_estimated": { "type": "number" }, "pricing_version": { "type": "string" }, "provider": { "type": "string" }, "provider_cents_per_unit": { "type": "number" }, "provider_cost_cents_actual": { "type": "number" }, "provider_cost_cents_estimated": { "type": "number" }, "provider_credits_actual": { "type": "number" }, "provider_credits_estimated": { "type": "number" }, "retail_credits_per_higgsfield_credit": { "type": "number" }, "retail_credits_per_unit": { "type": "number" }, "retail_credits_per_variant": { "type": "number" }, "total_credits_charged": { "type": "number" }, "total_credits_estimated": { "type": "number" } } }, "brand_kit_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_kit_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "estimated_cost_cents": { "type": "number" }, "format": { "anyOf": [ { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "3:4" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "16:9" ] } ] }, "frame_prompt": { "type": "string" }, "language": { "type": "string" }, "num_variants": { "type": "integer" }, "objective": { "anyOf": [ { "type": "string", "enum": [ "sales" ] }, { "type": "string", "enum": [ "awareness" ] }, { "type": "string", "enum": [ "traffic" ] }, { "type": "string", "enum": [ "leads" ] } ] }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "creativeHubDeleteImageCreativeGeneration", "summary": "Delete one image creative generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Soft-deletes one terminal image creative generation and its generated assets. Queued or processing generations cannot be deleted from the UI until they finish.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "assets_deleted", "deleted" ], "properties": { "assets_deleted": { "type": "integer" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/image-creatives/assets/{id}": { "delete": { "operationId": "creativeHubDeleteImageCreativeAsset", "summary": "Delete one image creative asset", "tags": [ "creative-hub", "creative-generation" ], "description": "Soft-deletes one generated image creative asset owned by the authenticated user. If the parent generation has no visible assets left, it is soft-deleted too.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "deleted", "generation_deleted" ], "properties": { "deleted": { "type": "boolean" }, "generation_deleted": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/image-studio/generate": { "post": { "operationId": "creativeHubGenerateCinematicImage", "summary": "Generate a cinematic image (async)", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous cinematic image generation and returns the queued generation metadata for polling. When one or more reference images are supplied (reference_image_url and/or reference_image_urls, capped at 4) the generation runs in image-to-image mode and is priced accordingly.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "minLength": 1, "maxLength": 4000, "type": "string" }, "style": { "maxLength": 64, "type": "string" }, "language": { "maxLength": 16, "type": "string" }, "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "3:4" ] } ] }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "num_variants": { "minimum": 1, "maximum": 4, "type": "integer" }, "brand_colors": { "maxItems": 5, "type": "array", "items": { "type": "string" } }, "brand_kit_id": { "minLength": 1, "maxLength": 100, "type": "string" }, "reference_image_url": { "maxLength": 2000, "type": "string" }, "reference_image_urls": { "maxItems": 4, "type": "array", "items": { "maxLength": 2000, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "created_at", "credits_estimated", "estimated_cost_cents", "generation_id", "polling_interval_ms", "status" ], "properties": { "created_at": { "type": "string" }, "credits_estimated": { "type": "integer" }, "estimated_cost_cents": { "type": "number" }, "generation_id": { "type": "string" }, "polling_interval_ms": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/image-studio/estimate": { "post": { "operationId": "creativeHubEstimateCinematicImage", "summary": "Estimate cinematic image generation credit cost", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the deterministic credit hold estimate for a cinematic image generation. The estimate resolves the SAME catalog model the generation will run on, so the style preset (which routes to different, differently-priced models) and any reference image are both reflected in the amount.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "num_variants" ], "properties": { "num_variants": { "minimum": 1, "maximum": 4, "type": "integer" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "style": { "maxLength": 64, "type": "string" }, "reference_image_url": { "maxLength": 2000, "type": "string" }, "reference_image_urls": { "maxItems": 4, "type": "array", "items": { "maxLength": 2000, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "credits", "model_id" ], "properties": { "credits": { "type": "integer" }, "model_id": { "description": "Catalog model the generation will be priced and run on.", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/image-studio/generations": { "get": { "operationId": "creativeHubListCinematicImageGenerations", "summary": "List cinematic image generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Lists cinematic image generations for the authenticated user and joins generated assets.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "batch_id", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generations", "next_cursor" ], "properties": { "generations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "assets", "batch_id", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "input", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "format", "height", "id", "kind", "name", "thumbnail_url", "url", "width" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "input": { "additionalProperties": false, "type": "object", "properties": { "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "3:4" ] } ] }, "estimated_cost_cents": { "type": "number" }, "num_variants": { "type": "integer" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "creativeHubDeleteCinematicImageGenerations", "summary": "Delete cinematic image generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Soft-deletes selected cinematic image generations for the authenticated user and soft-deletes their generated assets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/image-studio/generations/{id}": { "get": { "operationId": "creativeHubGetCinematicImageGeneration", "summary": "Get cinematic image generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns one cinematic image generation for polling/detail views.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "assets", "batch_id", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "input", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "format", "height", "id", "kind", "name", "thumbnail_url", "url", "width" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "input": { "additionalProperties": false, "type": "object", "properties": { "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "3:4" ] } ] }, "estimated_cost_cents": { "type": "number" }, "num_variants": { "type": "integer" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "style": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/library/folders": { "get": { "operationId": "creativeHubListFolders", "summary": "List Creative Hub library folders", "tags": [ "creative-hub", "creative-library" ], "description": "Lists Creative Hub library folders for the active team, optionally scoped to a parent folder for nested campaign or asset folders.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "asset" ] } ] }, "in": "query", "name": "kind", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "parent_id", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "kind", "parent_id", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "operationId": "creativeHubCreateFolder", "summary": "Create a Creative Hub library folder", "tags": [ "creative-hub", "creative-library" ], "description": "Creates a Creative Hub library folder in the active team. When parent_id is provided, the parent folder must exist in the same team and folder kind.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "kind", "name" ], "properties": { "kind": { "anyOf": [ { "type": "string", "enum": [ "campaign" ] }, { "type": "string", "enum": [ "asset" ] } ] }, "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "kind", "parent_id", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/library/folders/{id}": { "patch": { "operationId": "creativeHubRenameFolder", "summary": "Rename a Creative Hub library folder", "tags": [ "creative-hub", "creative-library" ], "description": "Renames a Creative Hub library folder in the active team. Returns 404 when the folder does not exist or is outside the caller scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "creativeHubDeleteFolder", "summary": "Delete a Creative Hub library folder", "tags": [ "creative-hub", "creative-library" ], "description": "Soft-deletes a Creative Hub library folder in the active team. Returns 404 when the folder does not exist or is outside the caller scope.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/library/assets": { "get": { "operationId": "creativeHubListAssets", "summary": "List Creative Hub library assets", "tags": [ "creative-hub", "creative-library" ], "description": "Lists Creative Hub assets for the active team with optional kind, folder and search filters. Results are cursor-paginated.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "kinds", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "folder_id", "required": false }, { "schema": { "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "kind", "url", "thumbnail_url", "format", "width", "height", "duration", "size_bytes", "folder_id", "source", "provider", "metadata", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string" }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/library/assets/upload": { "post": { "operationId": "creativeHubUploadAsset", "summary": "Upload an asset into the Creative Hub library", "tags": [ "creative-hub", "creative-library" ], "description": "Uploads one image, video or audio file into the active team library, validates MIME type and magic bytes where supported, and returns the created asset record.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "kind", "url", "thumbnail_url", "format", "width", "height", "duration", "size_bytes", "folder_id", "source", "provider", "metadata", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string" }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "415": { "description": "Response 415", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image, video, or audio asset." } }, "additionalProperties": false } } } } } }, "/api/v1/creative-hub/library/assets/import": { "post": { "operationId": "creativeHubImportAsset", "summary": "Import an existing creative URL into the library", "tags": [ "creative-hub", "creative-library" ], "description": "Registers an already generated or externally hosted creative URL as a Creative Hub library asset for the active team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "source_url", "kind" ], "properties": { "source_url": { "minLength": 1, "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "audio" ] }, { "type": "string", "enum": [ "voiceover" ] }, { "type": "string", "enum": [ "rich_media" ] }, { "type": "string", "enum": [ "avatar" ] } ] }, "name": { "maxLength": 200, "type": "string" }, "generation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rehost": { "type": "boolean" }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "kind", "url", "thumbnail_url", "format", "width", "height", "duration", "size_bytes", "folder_id", "source", "provider", "metadata", "created_at" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "type": "string" }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/library/assets/{id}": { "patch": { "operationId": "creativeHubRenameAsset", "summary": "Rename a Creative Hub library asset", "tags": [ "creative-hub", "creative-library" ], "description": "Renames one Creative Hub library asset in the active team. Returns 404 when the asset does not exist or is outside the caller scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/library/assets/move": { "post": { "operationId": "creativeHubMoveAssets", "summary": "Move Creative Hub library assets", "tags": [ "creative-hub", "creative-library" ], "description": "Moves one or more Creative Hub library assets into another folder, or to the library root when folder_id is null.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids", "folder_id" ], "properties": { "ids": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "moved" ], "properties": { "moved": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/library/assets/delete": { "post": { "operationId": "creativeHubDeleteAssets", "summary": "Delete Creative Hub library assets", "tags": [ "creative-hub", "creative-library" ], "description": "Soft-deletes one or more Creative Hub library assets in the active team.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/library/assets/{id}/save-to-drive": { "post": { "operationId": "creativeHubSaveAssetToDrive", "summary": "Save a Creative Hub library asset into the caller's Drive folder", "tags": [ "creative-hub", "creative-library" ], "description": "Copies a Creative Hub library asset into the current user's personal Google Drive folder, provisioning that folder on first use. Returns the created Drive file.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "object", "required": [ "id", "name", "mimeType", "size", "createdTime", "modifiedTime", "thumbnailUrl", "contentUrl", "viewUrl", "downloadUrl", "isVideo", "isImage", "isFolder", "parents" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mimeType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" }, "createdTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "modifiedTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVideo": { "type": "boolean" }, "isImage": { "type": "boolean" }, "isFolder": { "type": "boolean" }, "parents": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/thumbnail/{fileId}": { "get": { "operationId": "creativeHubThumbnail", "summary": "Proxy thumbnail image from Google Drive (images) or S3 cache (videos)", "tags": [ "creative-hub" ], "description": "Serves a thumbnail for a Drive file as raw image bytes, gated on a signed capability token (?cap=) bound to the fileId. Uses in-memory cache, then S3 cache for videos, then Drive thumbnail link for images. Response body is binary image data (image/jpeg or image/png); error responses are JSON.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cap", "required": false, "description": "Required signed, expiring capability token bound to this fileId and the issuing tenant. Minted by the authenticated Creative Hub file list/library responses or the media-capabilities endpoint. Missing/invalid/expired/wrong-file tokens are rejected with 403." }, { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Drive file thumbnail image.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/creative-hub/files/{fileId}/content": { "get": { "operationId": "creativeHubFileContent", "summary": "Stream file content for preview (supports Range requests for video)", "tags": [ "creative-hub" ], "description": "Proxies file content from Google Drive for browser preview as a streamed body, gated on a signed capability token (?cap=) bound to the fileId. Supports HTTP Range requests for video seeking (returns 206 Partial Content with Content-Range header). Response body is the raw file stream with the file's original Content-Type; error responses are JSON.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cap", "required": false, "description": "Required signed, expiring capability token bound to this fileId and the issuing tenant. Minted by the authenticated Creative Hub file list/library responses or the media-capabilities endpoint. Missing/invalid/expired/wrong-file tokens are rejected with 403." }, { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "responses": { "200": { "description": "Drive file content stream. Honors Range requests (returns 206 Partial Content with Content-Range for video seeking). Content-Type matches the original file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/*": { "schema": { "type": "string", "format": "binary" } }, "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Drive file content stream. Honors Range requests (returns 206 Partial Content with Content-Range for video seeking). Content-Type matches the original file. Partial content response for HTTP Range requests.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "video/*": { "schema": { "type": "string", "format": "binary" } }, "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/creative-hub/products": { "get": { "operationId": "getApiV1CreativeHubProducts", "summary": "List Creative Hub products", "tags": [ "creative-hub" ], "description": "Returns the active workspace scope team product catalog for Creative Hub generation flows.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "q", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "description", "source", "external_ref", "image_url", "images", "price", "currency", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1CreativeHubProducts", "summary": "Create Creative Hub product", "tags": [ "creative-hub" ], "description": "Creates a product entry in the active workspace scope team catalog.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "shopify" ] }, { "type": "string", "enum": [ "url" ] }, { "type": "string", "enum": [ "manual" ] }, { "type": "string", "enum": [ "feed" ] } ] }, "external_ref": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "description", "source", "external_ref", "image_url", "images", "price", "currency", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/products/{id}": { "patch": { "operationId": "patchApiV1CreativeHubProductsById", "summary": "Update Creative Hub product", "tags": [ "creative-hub" ], "description": "Updates a product entry in the active workspace scope team catalog.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 200, "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "shopify" ] }, { "type": "string", "enum": [ "url" ] }, { "type": "string", "enum": [ "manual" ] }, { "type": "string", "enum": [ "feed" ] } ] }, "external_ref": { "anyOf": [ { "maxLength": 300, "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "maxLength": 60, "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "description", "source", "external_ref", "image_url", "images", "price", "currency", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "format": "uuid", "type": "string" }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1CreativeHubProductsById", "summary": "Delete Creative Hub product", "tags": [ "creative-hub" ], "description": "Soft-deletes a product entry from the active workspace scope team catalog.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/products/import-url": { "post": { "operationId": "postApiV1CreativeHubProductsImportUrl", "summary": "Preview product import from URL", "tags": [ "creative-hub" ], "description": "Scrapes a product URL and returns a non-persisted product preview for user confirmation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 4, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "description", "source", "external_ref", "image_url", "images", "price", "metadata" ], "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "url" ] }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "string" } }, "price": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "$comment": "json-value" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/products/import-feed": { "post": { "operationId": "postApiV1CreativeHubProductsImportFeed", "summary": "Import products from CSV feed", "tags": [ "creative-hub" ], "description": "Parses and imports product rows from a CSV feed into the active workspace scope team catalog.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "csv" ], "properties": { "csv": { "minLength": 1, "maxLength": 2000000, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "imported" ], "properties": { "imported": { "minimum": 0, "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "Unprocessable entity - semantic validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/projects": { "get": { "operationId": "creativeHubListProjects", "summary": "List Creative Hub editor projects", "tags": [ "creative-hub", "creative-editors" ], "description": "Lists video-editor / rich-media projects for the active team (paginated by created_at cursor).", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "video_editor" ] }, { "type": "string", "enum": [ "rich_media" ] } ] }, "in": "query", "name": "kind", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "default": 30, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "name", "status", "document", "export_asset_ids", "thumbnail_url", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "document": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "export_asset_ids": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "post": { "operationId": "creativeHubCreateProject", "summary": "Create a Creative Hub editor project", "tags": [ "creative-hub", "creative-editors" ], "description": "Creates a video-editor or rich-media project for the active team and stores the optional editor document JSON envelope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "kind", "name" ], "properties": { "kind": { "anyOf": [ { "type": "string", "enum": [ "video_editor" ] }, { "type": "string", "enum": [ "rich_media" ] } ] }, "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "document": { "anyOf": [ { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, { "type": "null" } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "name", "status", "document", "export_asset_ids", "thumbnail_url", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "document": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "export_asset_ids": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/projects/{id}": { "get": { "operationId": "creativeHubGetProject", "summary": "Get a Creative Hub editor project", "tags": [ "creative-hub", "creative-editors" ], "description": "Returns one video-editor or rich-media project owned by an accessible team, including the saved editor document JSON.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "name", "status", "document", "export_asset_ids", "thumbnail_url", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "document": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "export_asset_ids": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "patch": { "operationId": "creativeHubUpdateProject", "summary": "Update a Creative Hub editor project (name / document / thumbnail)", "tags": [ "creative-hub", "creative-editors" ], "description": "Updates mutable project fields for a video-editor or rich-media project, preserving team ownership and returning the saved project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "document": { "anyOf": [ { "description": "JSON object with nested arrays and objects.", "type": "object", "additionalProperties": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "name", "status", "document", "export_asset_ids", "thumbnail_url", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "document": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "export_asset_ids": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "operationId": "creativeHubDeleteProject", "summary": "Soft-delete a Creative Hub editor project", "tags": [ "creative-hub", "creative-editors" ], "description": "Soft-deletes one accessible Creative Hub editor project. The project is hidden from subsequent list and get calls.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/projects/{id}/export": { "post": { "operationId": "creativeHubExportProject", "summary": "Link exported creative_asset ids to a project and mark it exported", "tags": [ "creative-hub", "creative-editors" ], "description": "Records already produced Creative Hub asset IDs on a project and returns the updated project marked as exported.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "asset_ids" ], "properties": { "asset_ids": { "minItems": 1, "type": "array", "items": { "format": "uuid", "type": "string" } } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "kind", "name", "status", "document", "export_asset_ids", "thumbnail_url", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "document": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "export_asset_ids": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/share": { "post": { "operationId": "creativeHubShare", "summary": "Share user folder with a Gmail/Workspace account", "tags": [ "creative-hub" ], "description": "Grants writer access to the user's Drive folder for the specified email and saves the sharing record. Returns a localized message and the updated list of authorized emails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "format": "email", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "emails" ], "properties": { "message": { "type": "string" }, "emails": { "type": "array", "items": { "format": "email", "type": "string" } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/unshare": { "post": { "operationId": "creativeHubUnshare", "summary": "Remove sharing access for a Gmail/Workspace account", "tags": [ "creative-hub" ], "description": "Revokes Drive folder access for the specified email and removes the sharing record. Returns a localized message and the updated list of remaining authorized emails.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "format": "email", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "emails" ], "properties": { "message": { "type": "string" }, "emails": { "type": "array", "items": { "format": "email", "type": "string" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/shared-emails": { "get": { "operationId": "creativeHubListSharedEmails", "summary": "Get list of emails with access to user folder", "tags": [ "creative-hub" ], "description": "Returns the list of email addresses that currently have access to the user's Drive folder.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "format": "email", "type": "string" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/subtitles/estimate": { "get": { "operationId": "creativeHubEstimateSubtitles", "summary": "Estimate subtitle generation credits", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the credit estimate for burning subtitles into a video (transcription is billed per second). Pass asset_id to price an uploaded team video asset: when that asset carries a recorded duration the estimate reads it, which is the same value the generation hold uses. Otherwise the estimate echoes the declared duration_seconds — asset_id never turns a successful estimate into an error.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "asset_id", "required": false }, { "schema": { "minimum": 1, "maximum": 600, "type": "number" }, "in": "query", "name": "duration_seconds", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "duration_seconds", "estimated_credits" ], "properties": { "duration_seconds": { "type": "integer" }, "estimated_credits": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/subtitles/generate": { "post": { "operationId": "creativeHubGenerateSubtitles", "summary": "Burn subtitles into an uploaded video", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous subtitle generation for a team video asset: the audio track is transcribed with Whisper, optionally translated to the requested language, and burned into the video. Returns a polling handle for GET /creative-hub/generations/{id}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "asset_id", "duration_seconds" ], "properties": { "asset_id": { "format": "uuid", "type": "string" }, "duration_seconds": { "minimum": 1, "maximum": 600, "type": "number" }, "language": { "maxLength": 32, "type": "string" }, "text_color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "position": { "anyOf": [ { "type": "string", "enum": [ "top" ] }, { "type": "string", "enum": [ "middle" ] }, { "type": "string", "enum": [ "bottom" ] } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generation_id", "status", "estimated_credits", "polling_interval_ms" ], "properties": { "generation_id": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "estimated_credits": { "type": "integer" }, "polling_interval_ms": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/credits": { "get": { "operationId": "creativeHubGetCredits", "summary": "Creative Hub credit balance", "tags": [ "creative-hub" ], "description": "Returns spendable AI credits for Creative Hub generation, including purchased credits and weekly grant credits.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "grant_balance", "monthly_cap", "monthly_used", "spendable", "total_purchased", "total_used" ], "properties": { "balance": { "type": "number" }, "grant_balance": { "type": "number" }, "monthly_cap": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthly_used": { "type": "number" }, "spendable": { "type": "number" }, "total_purchased": { "type": "number" }, "total_used": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/ugc/products/upload": { "post": { "operationId": "creativeHubUploadUgcProductImage", "summary": "Upload a product image for UGC product-hand mode", "tags": [ "creative-hub", "creative-generation" ], "description": "Uploads one JPEG, PNG or WebP product image for the UGC product-hand generation mode and stores it in team-scoped creative asset storage.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "image_url", "storage_key" ], "properties": { "image_url": { "type": "string" }, "storage_key": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, or WebP product image." } }, "additionalProperties": false } } } } } }, "/api/v1/creative-hub/ugc/audio/upload": { "post": { "operationId": "creativeHubUploadUgcAudio", "summary": "Upload an audio track to the voiceover library", "tags": [ "creative-hub", "creative-generation" ], "description": "Uploads one MP3 or WAV audio track into the team voiceover library (Voices page) and returns the stored URL plus a best-effort duration probe.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "audio_url", "storage_key" ], "properties": { "audio_url": { "type": "string" }, "duration_seconds": { "type": "number" }, "storage_key": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "MP3 or WAV audio track." } }, "additionalProperties": false } } } } } }, "/api/v1/creative-hub/ugc/models": { "get": { "operationId": "creativeHubListUgcModels", "summary": "List available UGC avatar/lip-sync models and Marketing Studio generation modes", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the curated UGC avatar/lip-sync model choices and the hardcoded Higgsfield Marketing Studio `mode` catalog (talking head, product review, how-to, unboxing, showcase) available to the composer.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "marketing_studio_modes" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "description", "is_default" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_default": { "type": "boolean" } } } }, "marketing_studio_modes": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "description", "is_default" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "is_default": { "type": "boolean" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/ugc/generate": { "post": { "operationId": "creativeHubGenerateUgc", "summary": "Generate a UGC video (async)", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous UGC video generation. When brand_kit_id is provided, the selected team Brand Kit is folded into the script, frame and motion prompt context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "mode", "settings" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "your_script" ] }, { "type": "string", "enum": [ "ai_script" ] }, { "type": "string", "enum": [ "product_hand" ] } ] }, "icp_type": { "anyOf": [ { "type": "string", "enum": [ "ecom" ] }, { "type": "string", "enum": [ "affiliate" ] }, { "type": "string", "enum": [ "leadgen" ] } ] }, "avatar_id": { "type": "string" }, "brand_kit_id": { "minLength": 1, "maxLength": 100, "type": "string" }, "product_id": { "type": "string" }, "product_description": { "maxLength": 2000, "type": "string" }, "script": { "maxLength": 4000, "type": "string" }, "hook_key": { "type": "string" }, "product_image_url": { "type": "string" }, "settings": { "type": "object", "properties": { "platform": { "anyOf": [ { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "instagram" ] }, { "type": "string", "enum": [ "youtube" ] } ] }, "format": { "anyOf": [ { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] }, { "type": "string", "enum": [ "4:5" ] }, { "type": "string", "enum": [ "16:9" ] } ] }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "480p" ] }, { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "language": { "type": "string" }, "captions": { "type": "boolean" }, "duration_seconds": { "minimum": 3, "maximum": 15, "type": "integer" }, "marketing_studio_mode": { "anyOf": [ { "type": "string", "enum": [ "ugc" ] }, { "type": "string", "enum": [ "product_review" ] }, { "type": "string", "enum": [ "ugc_how_to" ] }, { "type": "string", "enum": [ "ugc_unboxing" ] }, { "type": "string", "enum": [ "product_showcase" ] } ] } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "type": "object", "required": [ "created_at", "credits_estimated", "estimated_cost_cents", "generation_id", "polling_interval_ms", "status" ], "properties": { "created_at": { "type": "string" }, "credits_estimated": { "type": "integer" }, "estimated_cost_cents": { "type": "integer" }, "generation_id": { "type": "string" }, "polling_interval_ms": { "type": "integer" }, "status": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "error" ], "properties": { "code": { "type": "string", "enum": [ "INSUFFICIENT_CREDITS" ] }, "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/ugc/estimate": { "post": { "operationId": "creativeHubEstimateUgc", "summary": "Estimate UGC generation credit cost", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the deterministic credit estimate for a UGC generation request without starting a provider job. The estimate is computed from the SAME resolved billing input the generate endpoint charges from, so it accounts for the two effects that used to make the charge exceed the quote: a spoken script longer than the requested duration extends the billable duration (up to 15s, reported as duration_source), and a product photo adds a product-description line. Supply script_word_count and has_product_image to get the exact amount that will be charged; omitting them yields the floor of that amount — and in that case credits_max is the ceiling the charge can never exceed for this request, so the guaranteed invariant is credits <= charged <= credits_max. script_word_count_declared says which of the two you are looking at.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "mode", "duration_seconds" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "your_script" ] }, { "type": "string", "enum": [ "ai_script" ] }, { "type": "string", "enum": [ "product_hand" ] } ] }, "duration_seconds": { "minimum": 3, "maximum": 15, "type": "integer" }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "480p" ] }, { "type": "string", "enum": [ "720p" ] }, { "type": "string", "enum": [ "1080p" ] } ] }, "captions": { "type": "boolean" }, "has_product_image": { "description": "Whether a product photo will be attached. It triggers a real product-description model call, so it raises the estimate. mode=product_hand implies true (the photo is mandatory there).", "type": "boolean" }, "script_word_count": { "minimum": 0, "maximum": 2000, "description": "Word count of the user-supplied script (not the script itself — this endpoint performs no I/O and stores nothing). Used to detect a spoken duration longer than duration_seconds. Ignored for mode=ai_script, where the script is written to fit the requested duration.", "type": "integer" }, "model_id": { "deprecated": true, "description": "DEPRECATED and ignored: the UGC engine model is not caller-selectable. Kept so existing SDK clients that still send it do not start failing schema validation. It will be removed in a future major version.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "credits", "credits_max", "script_word_count_declared", "breakdown", "billable_seconds", "duration_source", "resolution_multiplier", "pricing_version" ], "properties": { "credits": { "description": "Total credits that will be held and charged.", "type": "integer" }, "credits_max": { "description": "Upper bound of what generate can charge for this exact request. It folds the only two inputs this endpoint cannot see: a spoken script that stretches the billable duration to the 15s product cap, and an attached product photo. Equal to credits when neither can apply.", "type": "integer" }, "script_word_count_declared": { "description": "False when script_word_count was omitted (or 0) on a mode that can be extended by the spoken script: the quote is then a floor, not the exact charge. Always true for mode=ai_script, where the script is written to fit the requested duration and never extends it.", "type": "boolean" }, "breakdown": { "description": "Per catalog line contribution to the total.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "model_id", "retail_credits", "unit", "units" ], "properties": { "model_id": { "type": "string" }, "retail_credits": { "type": "integer" }, "unit": { "type": "string" }, "units": { "type": "number" } } } }, "billable_seconds": { "description": "Seconds actually billed (minimum 8s, capped at 15s).", "type": "integer" }, "duration_source": { "description": "extended_to_spoken means the spoken script is longer than the requested duration, so the billable duration was raised to fit it.", "anyOf": [ { "type": "string", "enum": [ "requested" ] }, { "type": "string", "enum": [ "extended_to_spoken" ] } ] }, "resolution_multiplier": { "type": "number" }, "pricing_version": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/ugc/generations": { "get": { "operationId": "creativeHubListUgcGenerations", "summary": "List UGC video generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns paginated UGC video generation records for the authenticated user, including linked generated assets when available.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "batch_id", "required": false }, { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generations", "next_cursor" ], "properties": { "generations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "mode", "status", "batch_id", "settings", "result_asset_ids", "credits_estimated", "credits_charged", "error_message", "created_at", "completed_at", "assets" ], "properties": { "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "result_asset_ids": { "type": "array", "items": { "type": "string" } }, "credits_estimated": { "type": "integer" }, "credits_charged": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "kind", "format", "url", "thumbnail_url", "duration" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/ugc/generations/{id}": { "get": { "operationId": "creativeHubGetUgcGeneration", "summary": "Get one UGC video generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the current status, settings and generated assets for one UGC video generation owned by the authenticated user.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "mode", "status", "batch_id", "settings", "result_asset_ids", "credits_estimated", "credits_charged", "error_message", "created_at", "completed_at", "assets" ], "properties": { "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "result_asset_ids": { "type": "array", "items": { "type": "string" } }, "credits_estimated": { "type": "integer" }, "credits_charged": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "kind", "format", "url", "thumbnail_url", "duration" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "creativeHubDeleteUgcGeneration", "summary": "Delete one UGC generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Soft-deletes one terminal UGC video generation owned by the authenticated user and soft-deletes any generated assets linked to it. Queued or processing generations cannot be deleted until they finish.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "assets_deleted", "deleted" ], "properties": { "assets_deleted": { "type": "integer" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/ugc/hooks": { "get": { "operationId": "creativeHubListUgcHooks", "summary": "List UGC script hooks", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the curated script hook options for the requested ICP type, used by the UGC composer.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "icp_type", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "hooks" ], "properties": { "hooks": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/video-editor/clips": { "get": { "operationId": "creativeHubListVideoEditorClips", "summary": "List team video clips available to the video editor", "tags": [ "creative-hub", "creative-editors" ], "description": "Lists recent team-scoped Creative Hub video assets that can be selected as clips in the video editor timeline.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 60, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "url", "thumbnail_url", "duration" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/video-editor/render": { "post": { "operationId": "creativeHubRenderVideoEditor", "summary": "Concatenate selected clips into a single mp4 (sync)", "tags": [ "creative-hub", "creative-editors" ], "description": "Synchronously renders the selected team video clips into a single MP4, stores the result as a Creative Hub asset and links it to a video-editor project.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_ids" ], "properties": { "asset_ids": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "type": "string" } }, "title": { "maxLength": 200, "type": "string" }, "music_url": { "maxLength": 2000, "type": "string" }, "project_id": { "format": "uuid", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "asset", "project_id" ], "properties": { "asset": { "type": "object", "required": [ "id", "url", "thumbnail_url", "duration" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, "project_id": { "type": "string" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/video-studio/generate": { "post": { "operationId": "creativeHubGenerateCinematicVideo", "summary": "Generate a cinematic video clip (async)", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous cinematic image-to-video generation. BREAKING: a start-frame image_url is now REQUIRED for every provider and text-to-video is no longer supported. An optional end_image_url closes the clip on a second frame (accepted by the provider for kling3_0; how faithfully each model honours it is DA CONFERMARE). Returns queued generation metadata for polling. The resolution field was removed: provider output resolution is fixed and not configurable via the Higgsfield CLI (DA CONFERMARE in staging).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "prompt", "image_url" ], "properties": { "prompt": { "minLength": 1, "maxLength": 4000, "type": "string" }, "image_url": { "minLength": 1, "maxLength": 2000, "type": "string" }, "end_image_url": { "minLength": 1, "maxLength": 2000, "type": "string" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "kling_3_0" ] }, { "type": "string", "enum": [ "veo_3_1" ] }, { "type": "string", "enum": [ "seedance_pro" ] } ] }, "duration": { "anyOf": [ { "type": "number", "enum": [ 4 ] }, { "type": "number", "enum": [ 5 ] }, { "type": "number", "enum": [ 6 ] }, { "type": "number", "enum": [ 8 ] }, { "type": "number", "enum": [ 10 ] } ] }, "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] } ] }, "style": { "maxLength": 64, "type": "string" }, "brand_kit_id": { "minLength": 1, "maxLength": 100, "type": "string" }, "brand_colors": { "maxItems": 5, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "created_at", "credits_estimated", "estimated_cost_cents", "generation_id", "polling_interval_ms", "status" ], "properties": { "created_at": { "type": "string" }, "credits_estimated": { "type": "integer" }, "estimated_cost_cents": { "type": "number" }, "generation_id": { "type": "string" }, "polling_interval_ms": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/video-studio/estimate": { "post": { "operationId": "creativeHubEstimateCinematicVideo", "summary": "Estimate cinematic video generation credit cost", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns the deterministic credit hold estimate for a cinematic video generation, from the same catalog rates the generation is charged at.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "duration": { "anyOf": [ { "type": "number", "enum": [ 4 ] }, { "type": "number", "enum": [ 5 ] }, { "type": "number", "enum": [ 6 ] }, { "type": "number", "enum": [ 8 ] }, { "type": "number", "enum": [ 10 ] } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "kling_3_0" ] }, { "type": "string", "enum": [ "veo_3_1" ] }, { "type": "string", "enum": [ "seedance_pro" ] } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/video-studio/generations": { "get": { "operationId": "creativeHubListCinematicVideoGenerations", "summary": "List cinematic video generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Lists cinematic video generations for the authenticated user and joins generated video assets.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generations", "next_cursor" ], "properties": { "generations": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "assets", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "mode", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "duration", "format", "id", "kind", "name", "thumbnail_url", "url" ], "properties": { "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } } }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] } ] }, "duration_seconds": { "type": "integer" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "kling_3_0" ] }, { "type": "string", "enum": [ "veo_3_1" ] }, { "type": "string", "enum": [ "seedance_pro" ] } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "creativeHubDeleteCinematicVideoGenerations", "summary": "Delete cinematic video generations", "tags": [ "creative-hub", "creative-generation" ], "description": "Soft-deletes selected cinematic video generations for the authenticated user and soft-deletes their generated assets.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "minLength": 1, "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/creative-hub/video-studio/generations/{id}": { "get": { "operationId": "creativeHubGetCinematicVideoGeneration", "summary": "Get cinematic video generation", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns one cinematic video generation for polling/detail views.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "assets", "completed_at", "created_at", "credits_charged", "credits_estimated", "error_message", "id", "mode", "result_asset_ids", "settings", "status" ], "properties": { "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "duration", "format", "id", "kind", "name", "thumbnail_url", "url" ], "properties": { "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } } }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "credits_charged": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "credits_estimated": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_asset_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "settings": { "additionalProperties": false, "type": "object", "properties": { "aspect_ratio": { "anyOf": [ { "type": "string", "enum": [ "16:9" ] }, { "type": "string", "enum": [ "9:16" ] }, { "type": "string", "enum": [ "1:1" ] } ] }, "duration_seconds": { "type": "integer" }, "provider": { "anyOf": [ { "type": "string", "enum": [ "kling_3_0" ] }, { "type": "string", "enum": [ "veo_3_1" ] }, { "type": "string", "enum": [ "seedance_pro" ] } ] } } }, "status": { "anyOf": [ { "type": "string", "enum": [ "queued" ] }, { "type": "string", "enum": [ "processing" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "failed" ] } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/voices": { "get": { "operationId": "creativeHubListVoices", "summary": "List Creative Hub voiceover voices", "tags": [ "creative-hub", "creative-generation" ], "description": "Lists library and team-scoped voices available for Creative Hub voiceover generation, with optional gender, language, text search and scope filters.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "gender", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "language", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "q", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "library" ] }, { "type": "string", "enum": [ "mine" ] }, { "type": "string", "enum": [ "all" ] } ] }, "in": "query", "name": "scope", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "team_id", "created_by", "name", "provider", "provider_voice_id", "language", "gender", "accent", "descriptor", "preview_url", "is_library", "metadata", "created_at", "updated_at", "deleted_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "team_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_by": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provider": { "type": "string" }, "provider_voice_id": { "type": "string" }, "language": { "type": "string" }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "descriptor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_library": { "type": "boolean" }, "metadata": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "deleted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/voiceover/voices/{id}/preview": { "post": { "operationId": "creativeHubVoicePreview", "summary": "Get or lazily generate a short audio preview for a voice", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns a cached voice preview URL or generates and stores a short preview sample for the selected voice without charging credits.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/voiceover/estimate": { "post": { "operationId": "creativeHubEstimateVoiceover", "summary": "Estimate voiceover generation credits", "tags": [ "creative-hub", "creative-generation" ], "description": "Calculates character count, estimated credit cost and estimated duration for a single-voice or multi-voice voiceover request. The price is resolved from the provider of the selected voice (voice_id), which is the same provider the generation job will bill from — supplying a different voice can change the estimate by up to 6.6x.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "text": { "maxLength": 5000, "type": "string" }, "voice_id": { "type": "string" }, "language": { "maxLength": 10, "type": "string" }, "speed": { "minimum": 0.7, "maximum": 1.2, "type": "number" }, "sentiment": { "maxLength": 30, "type": "string" }, "multi_voice": { "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "voice_id", "text" ], "properties": { "voice_id": { "type": "string" }, "text": { "minLength": 1, "maxLength": 5000, "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "characters", "estimated_credits", "estimated_duration_s" ], "properties": { "characters": { "type": "integer" }, "estimated_credits": { "type": "integer" }, "estimated_duration_s": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/voiceover/generate": { "post": { "operationId": "creativeHubGenerateVoiceover", "summary": "Generate a voiceover asset", "tags": [ "creative-hub", "creative-generation" ], "description": "Starts an asynchronous Creative Hub voiceover generation for single-voice text or multi-voice dialogue and returns a polling handle.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "text": { "maxLength": 5000, "type": "string" }, "voice_id": { "type": "string" }, "language": { "maxLength": 10, "type": "string" }, "speed": { "minimum": 0.7, "maximum": 1.2, "type": "number" }, "sentiment": { "maxLength": 30, "type": "string" }, "multi_voice": { "maxItems": 20, "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "voice_id", "text" ], "properties": { "voice_id": { "type": "string" }, "text": { "minLength": 1, "maxLength": 5000, "type": "string" } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "generation_id", "status", "estimated_credits", "polling_interval_ms" ], "properties": { "generation_id": { "format": "uuid", "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "estimated_credits": { "type": "integer" }, "polling_interval_ms": { "type": "integer" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Response 402", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/creative-hub/generations/{id}": { "get": { "operationId": "creativeHubGetGenerationStatus", "summary": "Get Creative Hub generation status", "tags": [ "creative-hub", "creative-generation" ], "description": "Returns polling status for a Creative Hub voiceover or avatar generation and includes generated asset URLs once completed.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "id", "kind", "status", "credits_charged", "error_message", "assets" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "credits_charged": { "type": "integer" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assets": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "kind", "name", "url", "thumbnail_url", "duration" ], "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/cron/collect-insights": { "post": { "operationId": "triggerInsightCollection", "summary": "Trigger insight collection", "tags": [ "cron" ], "description": "Manually triggers insight collection from Meta API for the authenticated user and their team. Runs asynchronously in the background.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string" }, "to_date": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "job_id", "from_date", "to_date" ], "properties": { "message": { "type": "string" }, "job_id": { "type": "string" }, "from_date": { "type": "string" }, "to_date": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cron/collect-account-extended": { "post": { "operationId": "triggerAccountExtendedCollection", "summary": "Trigger account extended data collection", "tags": [ "cron" ], "description": "Triggers collection of extended account data (spend_cap, balance, payment method) from Meta API for all team accounts.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "job_id" ], "properties": { "message": { "type": "string" }, "job_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cron/status": { "get": { "operationId": "getCronStatus", "summary": "Get latest collection status", "tags": [ "cron" ], "description": "Returns the status of the most recent insight collection or other cron job for the user's team.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "job_type", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "created_at", "completed_at", "data" ], "properties": { "status": { "description": "Lifecycle state of a job_result row. \"NONE\" means no job has been recorded yet.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "RUNNING" ] }, { "type": "string", "enum": [ "COMPLETED" ] }, { "type": "string", "enum": [ "FAILED" ] }, { "type": "string", "enum": [ "NONE" ] } ] }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "data": { "anyOf": [ { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cron/fetch-exchange-rates": { "post": { "operationId": "fetchExchangeRates", "summary": "Fetch exchange rates from ExchangeRate-API", "tags": [ "cron" ], "description": "Fetches and stores exchange rates from ExchangeRate-API.com for the specified date (or today). Used for currency conversion in insights.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "description": "YYYY-MM-DD, defaults to today", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "date" ], "properties": { "message": { "type": "string" }, "date": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/cron/check-notifications": { "post": { "operationId": "triggerNotificationChecker", "summary": "Trigger notification checker", "tags": [ "cron" ], "description": "Triggers the notification checker for disapproved campaigns/adsets and spend cap alerts. Runs asynchronously for all team sessions.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "job_id" ], "properties": { "message": { "type": "string" }, "job_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cron/health": { "get": { "operationId": "getApiV1CronHealth", "summary": "Get cron jobs health status", "tags": [ "cron" ], "description": "Returns health status of all cron job types, including latest run status and 24-hour job/failure counts.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "insight_collection", "account_extended", "notification_checker", "total_jobs_24h", "failed_jobs_24h" ], "properties": { "insight_collection": { "type": "object", "required": [ "status" ], "properties": { "job_type": { "type": "string" }, "status": { "description": "Status of the latest run for this job type. \"UNKNOWN\" means no recent run was found.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "RUNNING" ] }, { "type": "string", "enum": [ "COMPLETED" ] }, { "type": "string", "enum": [ "FAILED" ] }, { "type": "string", "enum": [ "UNKNOWN" ] } ] }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "account_extended": { "type": "object", "required": [ "status" ], "properties": { "job_type": { "type": "string" }, "status": { "description": "Status of the latest run for this job type. \"UNKNOWN\" means no recent run was found.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "RUNNING" ] }, { "type": "string", "enum": [ "COMPLETED" ] }, { "type": "string", "enum": [ "FAILED" ] }, { "type": "string", "enum": [ "UNKNOWN" ] } ] }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "notification_checker": { "type": "object", "required": [ "status" ], "properties": { "job_type": { "type": "string" }, "status": { "description": "Status of the latest run for this job type. \"UNKNOWN\" means no recent run was found.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "RUNNING" ] }, { "type": "string", "enum": [ "COMPLETED" ] }, { "type": "string", "enum": [ "FAILED" ] }, { "type": "string", "enum": [ "UNKNOWN" ] } ] }, "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "total_jobs_24h": { "type": "number" }, "failed_jobs_24h": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cron/backfill-insights": { "post": { "operationId": "postApiV1CronBackfillInsights", "summary": "Trigger historical insights backfill", "tags": [ "cron" ], "description": "Triggers a historical insights backfill via SQS workers. Splits the date range into 30-day chunks. Super admin only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_date", "to_date" ], "properties": { "from_date": { "description": "Start date YYYY-MM-DD", "type": "string" }, "to_date": { "description": "End date YYYY-MM-DD", "type": "string" }, "user_id": { "format": "uuid", "description": "Specific session to backfill. Omit for all accessible sessions.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "runs", "from_date", "to_date", "chunks" ], "properties": { "message": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "required": [ "user_id", "worker_run_id", "chunks" ], "properties": { "user_id": { "type": "string" }, "worker_run_id": { "type": "string" }, "chunks": { "type": "number" } } } }, "from_date": { "type": "string" }, "to_date": { "type": "string" }, "chunks": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/cron/backfill-geo-insights": { "post": { "operationId": "postApiV1CronBackfillGeoInsights", "summary": "Trigger historical per-country (geo) insights backfill", "tags": [ "cron" ], "description": "Enqueues a historical campaign_country_daily_insight backfill via SQS, splitting the range into 30-day chunks. Fire-and-forget (BACKFILL_GEO_INSIGHTS is not a DB worker_type, so no worker_run is created); geo collection is idempotent. Super admin only. Omit user_id to backfill every accessible session.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_date", "to_date" ], "properties": { "from_date": { "description": "Start date YYYY-MM-DD", "type": "string" }, "to_date": { "description": "End date YYYY-MM-DD", "type": "string" }, "user_id": { "format": "uuid", "description": "Specific session to backfill. Omit for all accessible sessions.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "sessions", "enqueued", "from_date", "to_date", "chunks" ], "properties": { "message": { "type": "string" }, "sessions": { "type": "number" }, "enqueued": { "type": "number" }, "from_date": { "type": "string" }, "to_date": { "type": "string" }, "chunks": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/exchange-rates/latest": { "get": { "operationId": "getApiV1ExchangeRatesLatest", "summary": "Get latest exchange rates", "tags": [ "cron" ], "description": "Returns the most recent stored exchange rates for the given base currency (default EUR).", "parameters": [ { "schema": { "default": "EUR", "type": "string" }, "in": "query", "name": "base", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "rates", "date", "base" ], "properties": { "rates": { "type": "object", "additionalProperties": { "type": "number" } }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "base": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/cross-account-compare/metrics": { "get": { "operationId": "getCrossAccountMetrics", "summary": "Compare metrics across multiple Meta ad accounts", "tags": [ "analytics" ], "description": "Returns aggregated spend, CTR, ROAS, CPA and other metrics for 2-10 selected ad accounts in a given period.", "parameters": [ { "schema": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "account_ids", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "string", "enum": [ "account" ] } ] }, "in": "query", "name": "currency", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "accounts", "period", "currency" ], "properties": { "accounts": { "type": "array", "items": { "type": "object", "required": [ "account_id", "account_name", "currency", "spend", "impressions", "clicks", "ctr", "cpc", "cpm", "roas", "cpa", "conversions", "revenue" ], "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "currency": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "ctr": { "type": "number" }, "cpc": { "type": "number" }, "cpm": { "type": "number" }, "roas": { "type": "number" }, "cpa": { "type": "number" }, "conversions": { "type": "number" }, "revenue": { "type": "number" } } } }, "period": { "type": "object", "required": [ "from_date", "to_date" ], "properties": { "from_date": { "type": "string" }, "to_date": { "type": "string" } } }, "currency": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/cross-account-compare/trend": { "get": { "operationId": "getCrossAccountTrend", "summary": "Get overlay trend data for multiple Meta ad accounts", "tags": [ "analytics" ], "description": "Returns time-series data per account for rendering a multi-line overlay chart.", "parameters": [ { "schema": { "minItems": 2, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "in": "query", "name": "account_ids", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "from_date", "required": true }, { "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "in": "query", "name": "to_date", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "spend" ] }, { "type": "string", "enum": [ "roas" ] }, { "type": "string", "enum": [ "cpa" ] }, { "type": "string", "enum": [ "ctr" ] }, { "type": "string", "enum": [ "conversions" ] }, { "type": "string", "enum": [ "impressions" ] }, { "type": "string", "enum": [ "clicks" ] }, { "type": "string", "enum": [ "revenue" ] } ] }, "in": "query", "name": "metric", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "day" ] }, { "type": "string", "enum": [ "week" ] }, { "type": "string", "enum": [ "month" ] } ] }, "in": "query", "name": "granularity", "required": false }, { "schema": { "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "string", "enum": [ "account" ] } ] }, "in": "query", "name": "currency", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "metric", "granularity", "series" ], "properties": { "metric": { "type": "string" }, "granularity": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "required": [ "account_id", "account_name", "data" ], "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "date", "value" ], "properties": { "date": { "type": "string" }, "value": { "type": "number" } } } } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/webhooks/customerio/reporting": { "post": { "operationId": "postApiV1WebhooksCustomerioReporting", "summary": "Customer.io reporting webhook (delivery reconciliation)", "tags": [ "webhooks" ], "description": "Receives Customer.io delivery-state events and records them in cio_delivery_event. Verified via the CIO v0:: HMAC-SHA256 signature against CIO_REPORTING_WEBHOOK_SECRET.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true, "description": "Customer.io Reporting Webhook payload. Permissive on extra fields because the schema varies by object_type/metric and CIO may add fields without notice.", "type": "object", "required": [ "event_id", "metric" ], "properties": { "event_id": { "type": "string" }, "object_type": { "type": "string" }, "metric": { "type": "string" }, "timestamp": { "type": "number" }, "data": { "additionalProperties": true, "type": "object", "properties": { "delivery_id": { "type": "string" }, "customer_id": { "type": "string" }, "recipient": { "type": "string" }, "failure_message": { "type": "string" }, "identifiers": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } } }, "description": "Customer.io Reporting Webhook payload. Permissive on extra fields because the schema varies by object_type/metric and CIO may add fields without notice." }, "security": [ { "cioReportingSignature": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/dashboard-filter-presets": { "get": { "operationId": "listDashboardFilterPresets", "summary": "List dashboard filter presets", "tags": [ "dashboard-filter-presets" ], "description": "Returns the saved filter presets for the authenticated user on a dashboard page. Defaults to the main dashboard page when no page is provided.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "enum": [ "dashboard" ] }, { "type": "string", "enum": [ "analytics" ] }, { "type": "string", "enum": [ "reports" ] }, { "type": "string", "enum": [ "compare" ] } ] }, "in": "query", "name": "page", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "filters", "page", "sort_order", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "filters": { "additionalProperties": false, "type": "object", "properties": { "period": { "anyOf": [ { "type": "string", "enum": [ "today" ] }, { "type": "string", "enum": [ "yesterday" ] }, { "type": "string", "enum": [ "last_7d" ] }, { "type": "string", "enum": [ "last_14d" ] }, { "type": "string", "enum": [ "last_30d" ] }, { "type": "string", "enum": [ "this_week" ] }, { "type": "string", "enum": [ "last_week" ] }, { "type": "string", "enum": [ "this_month" ] }, { "type": "string", "enum": [ "last_month" ] }, { "type": "string", "enum": [ "custom" ] } ] }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "account_ids": { "type": "array", "items": { "type": "string" } }, "team_member_id": { "type": "string" }, "currency": { "type": "string" }, "entity_filters": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "level": { "maxLength": 20, "type": "string" }, "platform": { "maxLength": 20, "type": "string" }, "connected_only": { "type": "boolean" } } }, "page": { "type": "string" }, "sort_order": { "type": "number" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "createDashboardFilterPreset", "summary": "Create dashboard filter preset", "tags": [ "dashboard-filter-presets" ], "description": "Creates a named filter preset for the authenticated user. Preset names must be unique per page and user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "filters", "page" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "filters": { "additionalProperties": false, "type": "object", "properties": { "period": { "anyOf": [ { "type": "string", "enum": [ "today" ] }, { "type": "string", "enum": [ "yesterday" ] }, { "type": "string", "enum": [ "last_7d" ] }, { "type": "string", "enum": [ "last_14d" ] }, { "type": "string", "enum": [ "last_30d" ] }, { "type": "string", "enum": [ "this_week" ] }, { "type": "string", "enum": [ "last_week" ] }, { "type": "string", "enum": [ "this_month" ] }, { "type": "string", "enum": [ "last_month" ] }, { "type": "string", "enum": [ "custom" ] } ] }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "account_ids": { "type": "array", "items": { "type": "string" } }, "team_member_id": { "type": "string" }, "currency": { "type": "string" }, "entity_filters": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "level": { "maxLength": 20, "type": "string" }, "platform": { "maxLength": 20, "type": "string" }, "connected_only": { "type": "boolean" } } }, "page": { "anyOf": [ { "type": "string", "enum": [ "dashboard" ] }, { "type": "string", "enum": [ "analytics" ] }, { "type": "string", "enum": [ "reports" ] }, { "type": "string", "enum": [ "compare" ] } ] } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filters", "page", "sort_order", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "filters": { "additionalProperties": false, "type": "object", "properties": { "period": { "anyOf": [ { "type": "string", "enum": [ "today" ] }, { "type": "string", "enum": [ "yesterday" ] }, { "type": "string", "enum": [ "last_7d" ] }, { "type": "string", "enum": [ "last_14d" ] }, { "type": "string", "enum": [ "last_30d" ] }, { "type": "string", "enum": [ "this_week" ] }, { "type": "string", "enum": [ "last_week" ] }, { "type": "string", "enum": [ "this_month" ] }, { "type": "string", "enum": [ "last_month" ] }, { "type": "string", "enum": [ "custom" ] } ] }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "account_ids": { "type": "array", "items": { "type": "string" } }, "team_member_id": { "type": "string" }, "currency": { "type": "string" }, "entity_filters": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "level": { "maxLength": 20, "type": "string" }, "platform": { "maxLength": 20, "type": "string" }, "connected_only": { "type": "boolean" } } }, "page": { "type": "string" }, "sort_order": { "type": "number" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard-filter-presets/{id}": { "put": { "operationId": "updateDashboardFilterPreset", "summary": "Update dashboard filter preset", "tags": [ "dashboard-filter-presets" ], "description": "Updates a saved dashboard filter preset owned by the authenticated user, including name, filters, page or sort order.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "sort_order": { "minimum": 0, "type": "integer" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filters", "page", "sort_order", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "filters": { "additionalProperties": false, "type": "object", "properties": { "period": { "anyOf": [ { "type": "string", "enum": [ "today" ] }, { "type": "string", "enum": [ "yesterday" ] }, { "type": "string", "enum": [ "last_7d" ] }, { "type": "string", "enum": [ "last_14d" ] }, { "type": "string", "enum": [ "last_30d" ] }, { "type": "string", "enum": [ "this_week" ] }, { "type": "string", "enum": [ "last_week" ] }, { "type": "string", "enum": [ "this_month" ] }, { "type": "string", "enum": [ "last_month" ] }, { "type": "string", "enum": [ "custom" ] } ] }, "from_date": { "format": "date", "type": "string" }, "to_date": { "format": "date", "type": "string" }, "account_ids": { "type": "array", "items": { "type": "string" } }, "team_member_id": { "type": "string" }, "currency": { "type": "string" }, "entity_filters": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "level": { "maxLength": 20, "type": "string" }, "platform": { "maxLength": 20, "type": "string" }, "connected_only": { "type": "boolean" } } }, "page": { "type": "string" }, "sort_order": { "type": "number" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteDashboardFilterPreset", "summary": "Delete dashboard filter preset", "tags": [ "dashboard-filter-presets" ], "description": "Soft-deletes a dashboard filter preset owned by the authenticated user.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard-layouts": { "get": { "operationId": "getApiV1DashboardLayouts", "summary": "List dashboard layouts", "tags": [ "dashboard-layouts" ], "description": "Returns all saved dashboard layouts for the authenticated user, including whether any custom layouts exist.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "has_custom" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "user_id", "name", "config", "is_default", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } }, "has_custom": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1DashboardLayouts", "summary": "Create dashboard layout", "tags": [ "dashboard-layouts" ], "description": "Creates a new dashboard layout with the provided name and widget configuration. Optionally sets it as the default layout.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "name", "config" ], "properties": { "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "name", "config", "is_default", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard-layouts/active": { "get": { "operationId": "getApiV1DashboardLayoutsActive", "summary": "Get active dashboard layout", "tags": [ "dashboard-layouts" ], "description": "Returns the currently active dashboard layout. Falls back to the default layout or a virtual layout if none is set.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "layout", "config", "is_virtual" ], "properties": { "layout": { "anyOf": [ { "type": "object", "required": [ "id", "user_id", "name", "config", "is_default", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_virtual": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard-layouts/default-config": { "get": { "operationId": "getApiV1DashboardLayoutsDefaultConfig", "summary": "Get default config for role", "tags": [ "dashboard-layouts" ], "description": "Returns the default dashboard widget configuration for the authenticated user's role.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "config" ], "properties": { "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/dashboard-layouts/{id}": { "get": { "operationId": "getApiV1DashboardLayoutsById", "summary": "Get dashboard layout by ID", "tags": [ "dashboard-layouts" ], "description": "Returns a single dashboard layout by its ID. Only returns layouts owned by the authenticated user.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "name", "config", "is_default", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "patch": { "operationId": "patchApiV1DashboardLayoutsById", "summary": "Update dashboard layout", "tags": [ "dashboard-layouts" ], "description": "Partially updates a dashboard layout (name, config, and/or default flag). Returns 409 if the new name conflicts with an existing layout.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 255, "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "user_id", "name", "config", "is_default", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "user_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "config": { "$comment": "json-value", "description": "Arbitrary JSON value with nested arrays and objects." }, "is_default": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteApiV1DashboardLayoutsById", "summary": "Delete dashboard layout", "tags": [ "dashboard-layouts" ], "description": "Soft-deletes a dashboard layout by ID. Returns 404 if the layout does not exist or does not belong to the user.", "parameters": [ { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard/stats": { "get": { "operationId": "getDashboardStats", "summary": "Get dashboard statistics", "tags": [ "dashboard" ], "description": "Returns aggregated performance stats from the latest reports.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "user_id", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false, "description": "Target currency code (e.g. EUR, USD). Use \"account\" or omit for original currency." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "postback" ] }, { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "in": "query", "name": "conversion_source", "required": false, "description": "Revenue/conversion data source. \"postback\" (default) uses postback conversions; \"all\" aggregates platform-native purchase data across every platform; a platform value (e.g. \"meta\", \"google\") scopes platform-native revenue to that platform." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_spend", "total_impressions", "total_clicks", "total_conversions", "total_revenue", "roi", "avg_ctr", "campaigns_active", "campaigns_paused", "campaigns_total", "all_campaigns_active", "all_campaigns_paused", "all_campaigns_total", "currency", "accounts", "last_updated" ], "properties": { "total_spend": { "type": "number" }, "total_impressions": { "type": "number" }, "total_clicks": { "type": "number" }, "total_conversions": { "type": "number" }, "total_revenue": { "type": "number" }, "roi": { "type": "number" }, "avg_ctr": { "type": "number" }, "campaigns_active": { "type": "number" }, "campaigns_paused": { "type": "number" }, "campaigns_total": { "type": "number" }, "all_campaigns_active": { "type": "number" }, "all_campaigns_paused": { "type": "number" }, "all_campaigns_total": { "type": "number" }, "currency": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "account_id", "account_name", "spend", "impressions", "clicks", "campaigns", "currency" ], "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "campaigns": { "type": "number" }, "currency": { "type": "string" }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard/team-stats": { "get": { "operationId": "getDashboardTeamStats", "summary": "Get aggregated team statistics (owner only)", "tags": [ "dashboard" ], "description": "Returns aggregated performance stats across all team members. Only accessible by team owners and super admins.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "postback" ] }, { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "in": "query", "name": "conversion_source", "required": false, "description": "Revenue/conversion data source. \"postback\" (default) uses postback conversions; \"all\" aggregates platform-native purchase data across every platform; a platform value (e.g. \"meta\", \"google\") scopes platform-native revenue to that platform." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_spend", "total_impressions", "total_clicks", "total_conversions", "total_revenue", "roi", "avg_ctr", "campaigns_active", "campaigns_paused", "campaigns_total", "all_campaigns_active", "all_campaigns_paused", "all_campaigns_total", "members_count", "currency", "last_updated", "accounts" ], "properties": { "total_spend": { "type": "number" }, "total_impressions": { "type": "number" }, "total_clicks": { "type": "number" }, "total_conversions": { "type": "number" }, "total_revenue": { "type": "number" }, "roi": { "type": "number" }, "avg_ctr": { "type": "number" }, "campaigns_active": { "type": "number" }, "campaigns_paused": { "type": "number" }, "campaigns_total": { "type": "number" }, "all_campaigns_active": { "type": "number" }, "all_campaigns_paused": { "type": "number" }, "all_campaigns_total": { "type": "number" }, "members_count": { "type": "number" }, "currency": { "type": "string" }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accounts": { "type": "array", "items": { "type": "object", "required": [ "account_id", "account_name", "spend", "impressions", "clicks", "campaigns", "currency" ], "properties": { "account_id": { "type": "string" }, "account_name": { "type": "string" }, "spend": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "campaigns": { "type": "number" }, "currency": { "type": "string" }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/dashboard/daily": { "get": { "operationId": "getDashboardDaily", "summary": "Get daily performance breakdown for charting", "tags": [ "dashboard" ], "description": "Returns daily spend, revenue, profit, and conversion data for charting. Supports timezone conversion, currency conversion, and team/self scoping.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "from_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to_date", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "timezone", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "currency", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "user_id", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "self" ] }, { "type": "string", "enum": [ "team" ] } ] }, "in": "query", "name": "scope", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "postback" ] }, { "type": "string", "enum": [ "all" ] }, { "type": "string", "enum": [ "meta" ] }, { "type": "string", "enum": [ "google" ] }, { "type": "string", "enum": [ "tiktok" ] }, { "type": "string", "enum": [ "taboola" ] }, { "type": "string", "enum": [ "snapchat" ] }, { "type": "string", "enum": [ "outbrain" ] }, { "type": "string", "enum": [ "exoclick" ] } ] }, "in": "query", "name": "conversion_source", "required": false, "description": "Revenue/conversion data source. \"postback\" (default) uses postback conversions; \"all\" aggregates platform-native purchase data across every platform; a platform value (e.g. \"meta\", \"google\") scopes platform-native revenue to that platform." } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "days" ], "properties": { "days": { "type": "array", "items": { "type": "object", "required": [ "date", "spend", "revenue", "profit", "conversions" ], "properties": { "date": { "type": "string" }, "spend": { "type": "number" }, "revenue": { "type": "number" }, "profit": { "type": "number" }, "conversions": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/device-push/register": { "post": { "operationId": "registerDevicePushToken", "summary": "Register a native device push token", "tags": [ "device-push" ], "description": "Stores the APNs/FCM token of the mobile shell for the authenticated user so the backend can deliver native push notifications. Upserts on the token: a device re-registered by another user is re-assigned to that user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "token", "platform" ], "properties": { "token": { "minLength": 1, "maxLength": 512, "description": "APNs/FCM device registration token returned by the native push plugin.", "type": "string" }, "platform": { "description": "Native platform of the Capacitor shell that produced the token.", "anyOf": [ { "type": "string", "enum": [ "ios" ] }, { "type": "string", "enum": [ "android" ] } ] }, "user_agent": { "maxLength": 1024, "description": "Device label or User-Agent captured at registration.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/device-push/unregister": { "post": { "operationId": "unregisterDevicePushToken", "summary": "Unregister a native device push token", "tags": [ "device-push" ], "description": "Deletes the stored device push token, only if it belongs to the authenticated user. Idempotent: returns 200 even if the token was already removed or is owned by another user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "token" ], "properties": { "token": { "minLength": 1, "maxLength": 512, "description": "Device registration token to unregister.", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } } } } } } } }, "/api/v1/ads/duplicate": { "post": { "operationId": "duplicateAd", "summary": "Duplicate an ad", "tags": [ "campaigns" ], "description": "Creates a copy of an existing Meta ad. With reuse_post=true / post_id_mode=same_post (default) it uses /{ad_id}/copies when possible to preserve the original post and engagement; if Meta rejects a stored legacy creative, it rebuilds a sanitized creative on the same page. Other modes build a new creative (optionally on a different page) and create a fresh ad. Supports cross-account duplication via destination_account_id. Collection ads (\"inserzioni con raccolta\") reuse their existing Instant Experience (Canvas), which is bound to the original page, so they can only be duplicated on the same page (new_post_new_page to a different page returns 400).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ad_id", "account_id" ], "properties": { "ad_id": { "type": "string" }, "account_id": { "type": "string" }, "adset_id": { "type": "string" }, "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "reuse_post": { "type": "boolean" }, "destination_account_id": { "type": "string" }, "post_id_mode": { "anyOf": [ { "type": "string", "enum": [ "same_post" ] }, { "type": "string", "enum": [ "new_post_same_page" ] }, { "type": "string", "enum": [ "new_post_new_page" ] } ] }, "fan_page_id": { "type": "string" }, "creative_override": { "additionalProperties": false, "type": "object", "properties": { "primary_text": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "call_to_action": { "type": "string" }, "link": { "type": "string" }, "url_tags": { "type": "string" }, "fan_page_id": { "type": "string" }, "media": { "additionalProperties": false, "type": "object", "required": [ "type", "source_url" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] } ] }, "source_url": { "type": "string" } } } } } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ad_id", "message" ], "properties": { "ad_id": { "type": "string" }, "message": { "type": "string" }, "rename_failed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/adsets/duplicate": { "post": { "operationId": "duplicateAdSet", "summary": "Duplicate an ad set", "tags": [ "campaigns" ], "description": "Creates a copy of an existing Meta ad set. Uses the Graph API /{adset_id}/copies endpoint when possible, and falls back to a sequential rebuild when the source ad set has too many ads or Meta rejects a legacy stored creative during native copy. Supports cross-account duplication and post_id_mode (same_post / new_post_same_page / new_post_new_page).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "adset_id", "account_id" ], "properties": { "adset_id": { "type": "string" }, "account_id": { "type": "string" }, "campaign_id": { "type": "string" }, "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "deep_copy": { "type": "boolean" }, "destination_account_id": { "type": "string" }, "post_id_mode": { "anyOf": [ { "type": "string", "enum": [ "same_post" ] }, { "type": "string", "enum": [ "new_post_same_page" ] }, { "type": "string", "enum": [ "new_post_new_page" ] } ] }, "fan_page_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "adset_id", "message" ], "properties": { "adset_id": { "type": "string" }, "message": { "type": "string" }, "rename_failed": { "type": "boolean" }, "rename_error": { "type": "string" }, "partial": { "description": "True when the ad set was created but Meta rejected one or more ads. See `failures` for details.", "type": "boolean" }, "copied_ads": { "description": "Number of ads copied (only present for sequential/cross-account copies, not the native deep copy).", "type": "integer" }, "failures": { "description": "Per-child copy failures, with the Meta error message for each.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "level", "source_id", "error" ], "properties": { "level": { "anyOf": [ { "type": "string", "enum": [ "adset" ] }, { "type": "string", "enum": [ "ad" ] } ] }, "source_id": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/campaigns/duplicate": { "post": { "operationId": "duplicateCampaign", "summary": "Duplicate a campaign", "tags": [ "campaigns" ], "description": "Creates a copy of an existing Meta campaign. Uses the Graph API /{campaign_id}/copies endpoint when possible, and falls back to a sequential rebuild when the source campaign has too many nested objects or Meta rejects a legacy stored creative during native copy. Supports cross-account duplication and post_id_mode (same_post / new_post_same_page / new_post_new_page).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "account_id" ], "properties": { "campaign_id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "ACTIVE" ] }, { "type": "string", "enum": [ "PAUSED" ] } ] }, "deep_copy": { "type": "boolean" }, "destination_account_id": { "type": "string" }, "post_id_mode": { "anyOf": [ { "type": "string", "enum": [ "same_post" ] }, { "type": "string", "enum": [ "new_post_same_page" ] }, { "type": "string", "enum": [ "new_post_new_page" ] } ] }, "fan_page_id": { "type": "string" }, "start_time": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "message" ], "properties": { "campaign_id": { "type": "string" }, "message": { "type": "string" }, "rename_failed": { "type": "boolean" }, "rename_error": { "type": "string" }, "start_time_failed": { "type": "boolean" }, "start_time_error": { "type": "string" }, "partial": { "description": "True when the campaign was created but Meta rejected one or more ad sets/ads. See `failures` for details.", "type": "boolean" }, "copied_adsets": { "description": "Number of ad sets copied (only present for sequential/cross-account copies, not the native deep copy).", "type": "integer" }, "copied_ads": { "description": "Number of ads copied (only present for sequential/cross-account copies, not the native deep copy).", "type": "integer" }, "failures": { "description": "Per-child copy failures, with the Meta error message for each.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "level", "source_id", "error" ], "properties": { "level": { "anyOf": [ { "type": "string", "enum": [ "adset" ] }, { "type": "string", "enum": [ "ad" ] } ] }, "source_id": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/campaigns/duplicate/compatibility": { "post": { "operationId": "checkCampaignDuplicateCompatibility", "summary": "Pre-flight check for cross-account campaign duplication", "tags": [ "campaigns" ], "description": "Read-only check (does not duplicate anything): reports whether the destination Meta ad account has access to the Page, Pixel(s), Custom Audience(s) and Product Catalog(s) the source campaign depends on. A missing Page is blocking — nothing would be created in the destination account. A missing Pixel/Audience/Catalog is degraded — only the ad sets/ads that use it would fail to copy, the rest of the campaign still would.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "account_id", "destination_account_id" ], "properties": { "campaign_id": { "type": "string" }, "account_id": { "type": "string" }, "destination_account_id": { "type": "string" } } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "compatible", "missing" ], "properties": { "compatible": { "description": "False only when a blocking item (the Page) is inaccessible.", "type": "boolean" }, "missing": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "type", "id", "severity" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "page" ] }, { "type": "string", "enum": [ "pixel" ] }, { "type": "string", "enum": [ "audience" ] }, { "type": "string", "enum": [ "product_catalog" ] } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "blocking" ] }, { "type": "string", "enum": [ "degraded" ] } ] } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/fan-pages": { "get": { "operationId": "getApiV1FanPages", "summary": "Get fan pages (server-side paginated)", "tags": [ "fan-pages" ], "description": "Returns a server-side paginated, filtered, sorted list of Meta Fan Pages. Supports offset pagination, search, and multiple filter dimensions.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "query", "name": "member_id", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "fan_page_name" ] }, { "type": "string", "enum": [ "business_name" ] }, { "type": "string", "enum": [ "connected" ] }, { "type": "string", "enum": [ "is_active" ] }, { "type": "string", "enum": [ "created_at" ] } ] }, "in": "query", "name": "sort_by", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "asc" ] }, { "type": "string", "enum": [ "desc" ] } ] }, "in": "query", "name": "sort_order", "required": false }, { "schema": { "minLength": 2, "maxLength": 200, "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "connected" ] }, { "type": "string", "enum": [ "disconnected" ] } ] }, "in": "query", "name": "connected", "required": false }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "inactive" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "maxLength": 100, "type": "string" }, "in": "query", "name": "business_id", "required": false }, { "schema": { "maxLength": 20, "type": "string" }, "in": "query", "name": "ownership_type", "required": false }, { "schema": { "maxLength": 10, "type": "string" }, "in": "query", "name": "platform", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_from", "required": false }, { "schema": { "format": "date-time", "type": "string" }, "in": "query", "name": "created_to", "required": false } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total", "counts" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "fan_page_id", "fan_page_name", "business_id", "business_name", "connected", "is_active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "fan_page_id": { "type": "string" }, "fan_page_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "business_id": { "type": "string" }, "business_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "connected": { "type": "boolean" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "sheet_id": { "type": "string" }, "member_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "member_email": { "type": "string" }, "team_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "total": { "type": "integer" }, "counts": { "type": "object", "required": [ "total", "connected", "active" ], "properties": { "total": { "type": "integer" }, "connected": { "type": "integer" }, "active": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/fan-pages/businesses": { "get": { "operationId": "getApiV1FanPagesBusinesses", "summary": "List businesses available for fan pages", "tags": [ "fan-pages" ], "description": "Returns distinct Meta Business Manager ids and names represented by fan pages visible to the caller, respecting admin/team scoping.", "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/fan-pages/{fanPageId}/posts": { "get": { "operationId": "getApiV1FanPagesByFanPageIdPosts", "summary": "Get selectable posts for a fan page", "tags": [ "fan-pages" ], "description": "Returns the posts of a Meta fan page that can be used as an ad creative: published timeline posts plus the unpublished dark posts created inline by existing ads. Use is_published to tell them apart.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "fanPageId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "posts" ], "properties": { "posts": { "type": "array", "items": { "type": "object", "required": [ "id", "message", "full_picture", "created_time", "permalink_url", "is_published" ], "properties": { "id": { "type": "string" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "full_picture": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_time": { "type": "string" }, "permalink_url": { "type": "string" }, "is_published": { "description": "False for dark posts — page posts created inline as ad creatives. They are selectable as creative but have no publicly reachable permalink.", "type": "boolean" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/fan-pages/connect": { "post": { "operationId": "postApiV1FanPagesConnect", "summary": "Connect non-Meta fan pages", "tags": [ "fan-pages" ], "description": "Marks selected non-Meta fan pages or Snapchat public profiles as connected for sessions accessible to the current user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fan_page_ids" ], "properties": { "fan_page_ids": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/fan-pages/disconnect": { "post": { "operationId": "postApiV1FanPagesDisconnect", "summary": "Disconnect non-Meta fan pages", "tags": [ "fan-pages" ], "description": "Marks selected non-Meta fan pages or Snapchat public profiles as disconnected for sessions accessible to the current user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "fan_page_ids" ], "properties": { "fan_page_ids": { "minItems": 1, "type": "array", "items": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/changelog/ingest": { "post": { "operationId": "ingestFeaturebaseChangelog", "summary": "Create and publish a changelog from CI (shared-secret)", "tags": [ "featurebase" ], "description": "Webhook-style endpoint called by the GitHub Actions release pipeline. Creates a changelog entry on Featurebase, publishes it (locales default to the bilingual en+it entry, sendEmail opt-in default false) and persists the returned Featurebase post id onto the matching `release_artifact_link` (best-effort) so the publish-followup webhook can correlate status transitions to the release candidate. Auth is **NOT** via JWT - callers present a shared secret in the `x-changelog-ingest-key` header that must match the `CHANGELOG_INGEST_API_KEY` env var (compared with `timingSafeEqual`). Returns 503 when not configured (missing env var or Featurebase plugin), 401 on invalid/missing key, 502 when the Featurebase create/publish call fails. On success returns 201 with the published changelog entry. When the secret is absent the CI workflow falls back to the byte-equivalent direct publish, so this endpoint being unconfigured causes no regression.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "type": "string" }, "htmlContent": { "minLength": 1, "type": "string" }, "markdownContent": { "minLength": 1, "type": "string" }, "releaseCandidateId": { "minLength": 1, "type": "string" }, "locales": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } }, "sendEmail": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "header", "name": "x-changelog-ingest-key", "required": true } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "state", "date", "categories" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "state": { "type": "string" }, "date": { "type": "string" }, "categories": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/featurebase/changelog": { "get": { "operationId": "getApiV1FeaturebaseChangelog", "summary": "List published changelogs from Featurebase", "tags": [ "featurebase" ], "description": "Returns a paginated list of published changelog entries from Featurebase. Public endpoint.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sortBy", "required": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "state", "date", "categories" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "state": { "type": "string" }, "date": { "type": "string" }, "categories": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } }, "nextCursor": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "post": { "operationId": "postApiV1FeaturebaseChangelog", "summary": "Create a changelog entry on Featurebase", "tags": [ "featurebase" ], "description": "Creates a new changelog entry on Featurebase and optionally sends a Telegram notification.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "title", "markdownContent" ], "properties": { "title": { "minLength": 1, "type": "string" }, "markdownContent": { "minLength": 1, "type": "string" }, "releaseCandidateId": { "minLength": 1, "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "state", "date", "categories" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "state": { "type": "string" }, "date": { "type": "string" }, "categories": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/changelog/{id}": { "patch": { "operationId": "patchApiV1FeaturebaseChangelogById", "summary": "Update a changelog entry on Featurebase", "tags": [ "featurebase" ], "description": "Updates an existing changelog entry on Featurebase by ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "title": { "minLength": 1, "type": "string" }, "markdownContent": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "state", "date", "categories" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "state": { "type": "string" }, "date": { "type": "string" }, "categories": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/changelog/{id}/publish": { "post": { "operationId": "postApiV1FeaturebaseChangelogByIdPublish", "summary": "Publish a changelog entry on Featurebase", "tags": [ "featurebase" ], "description": "Publishes a draft changelog entry on Featurebase, making it visible to users.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "state", "date", "categories" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "state": { "type": "string" }, "date": { "type": "string" }, "categories": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/sso-token": { "get": { "operationId": "getApiV1FeaturebaseSsoToken", "summary": "Generate Featurebase SSO JWT for the current user", "tags": [ "featurebase" ], "description": "Generates a Featurebase SSO JWT token so the user can be authenticated in the Featurebase widget.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/roadmap": { "get": { "operationId": "getApiV1FeaturebaseRoadmap", "summary": "List roadmap posts from Featurebase", "tags": [ "featurebase" ], "description": "Returns a paginated list of roadmap posts from Featurebase with optional status and board filters. Public endpoint.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "sortBy", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "boardId", "required": false } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "status", "upvotes", "tags" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string" }, "upvotes": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "nextCursor": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/featurebase/roadmap/{id}/status": { "patch": { "operationId": "patchApiV1FeaturebaseRoadmapByIdStatus", "summary": "Update roadmap post status on Featurebase", "tags": [ "featurebase" ], "description": "Updates the status of a roadmap post on Featurebase by post ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "statusId" ], "properties": { "statusId": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "id", "title", "content", "status", "upvotes", "tags" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string" }, "upvotes": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/webhooks/featurebase": { "post": { "operationId": "postApiV1WebhooksFeaturebase", "summary": "Featurebase webhook endpoint", "tags": [ "webhooks" ], "description": "Receives Featurebase post/status events. Verified via HMAC-SHA256 over `.` against FEATUREBASE_WEBHOOK_SECRET, with a 5-minute timestamp tolerance (anti-replay). Both `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true, "description": "Featurebase webhook payload. Permissive on extra fields because Featurebase may add new event metadata without notice.", "type": "object", "required": [ "topic" ], "properties": { "topic": { "description": "Featurebase event topic, e.g. `changelog.published` or `post.updated`. Sent unprefixed by Featurebase.", "type": "string" }, "post_id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "status": { "type": "string" }, "delivery_id": { "type": "string" }, "timestamp": { "type": "string" } } } } }, "description": "Featurebase webhook payload. Permissive on extra fields because Featurebase may add new event metadata without notice." }, "security": [ { "featurebaseSignature": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status", "event_id" ], "properties": { "status": { "type": "string" }, "event_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/status": { "get": { "operationId": "getGa4Status", "summary": "Get the GA4 data-source connection status", "tags": [ "ga4" ], "description": "Returns whether the workspace has a Google Analytics 4 read connection, which property is selected, and when it was last read. `configured: false` means the server itself has no GA4 OAuth credentials.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "configured", "connected", "email", "token_status", "last_read_at", "property" ], "properties": { "configured": { "description": "False when the server has no GA4 OAuth credentials.", "type": "boolean" }, "connected": { "type": "boolean" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "token_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_read_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "property": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "id", "name", "currency", "timezone" ], "properties": { "id": { "description": "Numeric GA4 property id.", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/login-url": { "get": { "operationId": "getGa4LoginUrl", "summary": "Start the GA4 read-only OAuth flow", "tags": [ "ga4" ], "description": "Returns the Google consent URL for the `analytics.readonly` scope. The destination workspace is signed into the OAuth state, so the callback stamps the connection on the active team.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/properties": { "get": { "operationId": "listGa4Properties", "summary": "List the GA4 properties visible to the connected Google account", "tags": [ "ga4" ], "description": "Reads the GA4 Admin API account summaries with the stored consent. Returns 404 when the workspace has no GA4 connection and 401 when the consent was revoked.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "property_id", "display_name", "account_name" ], "properties": { "property_id": { "type": "string" }, "display_name": { "type": "string" }, "account_name": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/property": { "put": { "operationId": "selectGa4Property", "summary": "Select the GA4 property to read from", "tags": [ "ga4" ], "description": "Validates the property against the GA4 Admin API with the stored consent, then persists it (with its currency and timezone) on the workspace connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "property_id" ], "properties": { "property_id": { "minLength": 1, "maxLength": 50, "pattern": "^[0-9]+$", "type": "string" } } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "property" ], "properties": { "property": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "currency", "timezone" ], "properties": { "id": { "description": "Numeric GA4 property id.", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/connection": { "delete": { "operationId": "disconnectGa4", "summary": "Remove the GA4 data-source connection", "tags": [ "ga4" ], "description": "Deletes the stored consent and property selection for the workspace. Returns `disconnected: false` when there was nothing to remove.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "disconnected" ], "properties": { "disconnected": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden - caller lacks the required role/permission", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/ga4/overview": { "get": { "operationId": "getGa4Overview", "summary": "Read GA4 site metrics for a date range", "tags": [ "ga4" ], "description": "Runs two GA4 Data API reports on the selected property: totals (sessions, users, new users, page views, key events, revenue) and a breakdown by session source/medium and campaign. Returns 409 when no property is selected yet.", "parameters": [ { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "from", "required": true, "description": "Inclusive start date (YYYY-MM-DD), property timezone." }, { "schema": { "format": "date", "type": "string" }, "in": "query", "name": "to", "required": true, "description": "Inclusive end date (YYYY-MM-DD), property timezone." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "property", "currency", "date_range", "totals", "breakdown" ], "properties": { "property": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "timezone" ], "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "date_range": { "additionalProperties": false, "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "totals": { "additionalProperties": false, "type": "object", "required": [ "sessions", "users", "new_users", "page_views", "key_events", "revenue" ], "properties": { "sessions": { "type": "number" }, "users": { "type": "number" }, "new_users": { "type": "number" }, "page_views": { "type": "number" }, "key_events": { "type": "number" }, "revenue": { "type": "number" } } }, "breakdown": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "source_medium", "campaign", "sessions", "key_events", "revenue" ], "properties": { "source_medium": { "type": "string" }, "campaign": { "type": "string" }, "sessions": { "type": "number" }, "key_events": { "type": "number" }, "revenue": { "type": "number" } } } } } } } } }, "400": { "description": "Invalid request - schema validation failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict - resource state prevents the operation", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "502": { "description": "Bad gateway - upstream provider failed", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/geo-search": { "get": { "operationId": "getApiV1GeoSearch", "summary": "Search Meta geo locations for targeting", "tags": [ "targeting" ], "description": "Proxies Meta Marketing API geo location search for regions and cities.", "parameters": [ { "schema": { "minLength": 2, "maxLength": 100, "type": "string" }, "in": "query", "name": "q", "required": true, "description": "Search query (e.g. \"Lombardia\", \"Milano\")" }, { "schema": { "type": "string" }, "in": "query", "name": "location_types", "required": false, "description": "Comma-separated location types: region, city" }, { "schema": { "maxLength": 2, "type": "string" }, "in": "query", "name": "country_code", "required": false, "description": "Filter by country code (e.g. IT)" }, { "schema": { "type": "string" }, "in": "query", "name": "account_id", "required": true, "description": "Ad account ID to resolve token" }, { "schema": { "minimum": 1, "maximum": 25, "default": 10, "type": "integer" }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "locations" ], "properties": { "locations": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "type", "country_code", "country_name" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "country_code": { "type": "string" }, "country_name": { "type": "string" }, "region": { "type": "string" }, "region_id": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/webhooks/github/release-event": { "post": { "operationId": "postApiV1WebhooksGithubReleaseEvent", "summary": "GitHub release-event webhook endpoint", "tags": [ "webhooks" ], "description": "Receives release candidate events from GitHub Actions. Verified via HMAC-SHA256 signature (`x-hub-signature-256`) on the raw body against GITHUB_WEBHOOK_SECRET.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "pr_id", "title" ], "properties": { "pr_id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "branch": { "type": "string" }, "commit_sha": { "type": "string" }, "author": { "type": "string" }, "timestamp": { "type": "string" }, "clickup_task_id": { "type": "string" }, "content_type": { "type": "string" }, "product_area": { "type": "string" }, "impact_level": { "type": "string" }, "user_value_summary": { "type": "string" }, "delivery_id": { "type": "string" } } } } } }, "security": [ { "hmacSha256": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "202": { "description": "Accepted - processing asynchronously", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "status", "event_id" ], "properties": { "status": { "type": "string" }, "event_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/google/asset-groups/{assetGroupId}/assets": { "get": { "operationId": "getGoogleAssetGroupAssets", "summary": "Get persisted asset list for a Google PMax asset group", "tags": [ "google" ], "description": "Returns text + image asset metadata captured at publish time. Status is the snapshot at publish; live status sync is a separate worker.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "assetGroupId", "required": true } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "assets" ], "properties": { "assets": { "type": "array", "items": { "type": "object", "required": [ "id", "fieldType", "assetText", "assetImageUrl", "assetVideoId", "assetStatus", "updatedAt" ], "properties": { "id": { "type": "string" }, "fieldType": { "type": "string" }, "assetText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetVideoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/v1/google/search-term-campaigns": { "get": { "operationId": "listGoogleSearchTermCampaigns", "summary": "List Google Ads campaigns with synced search terms", "tags": [ "google" ], "description": "Returns campaigns discovered from the cached Google Ads search terms. Used as the campaign picker before listing semantic buckets, so buckets and apply-all actions stay campaign-scoped.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customer_id", "required": false, "description": "Google Ads customer (account) id." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "campaign_id", "campaign_name", "advertising_channel_type", "term_count", "unreviewed_count", "clicks", "cost_micros", "cost", "conversions" ], "properties": { "campaign_id": { "type": "string" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "advertising_channel_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "term_count": { "type": "number" }, "unreviewed_count": { "type": "number" }, "clicks": { "type": "number" }, "cost_micros": { "type": "number" }, "cost": { "type": "number" }, "conversions": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/google/search-term-buckets": { "get": { "operationId": "listGoogleSearchTermBuckets", "summary": "List Google Ads search-term semantic buckets", "tags": [ "google" ], "description": "Returns semantic buckets built from cached Google Ads search terms. Buckets are denormalized with counts, cost, conversions, representative terms, and AI-generated hints so the UI can review intent groups instead of raw term rows.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customer_id", "required": false, "description": "Google Ads customer (account) id." }, { "schema": { "type": "string" }, "in": "query", "name": "campaign_id", "required": false, "description": "Google Ads campaign id. Required by the UI." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "OPEN" ] }, { "type": "string", "enum": [ "EXCLUDED" ] }, { "type": "string", "enum": [ "KEPT" ] }, { "type": "string", "enum": [ "SNOOZED" ] }, { "type": "string", "enum": [ "ARCHIVED" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "minimum": 1, "maximum": 200, "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "customer_id", "campaign_id", "campaign_name", "advertising_channel_type", "label", "hint", "recommended_action", "status", "representative_terms", "term_count", "unreviewed_count", "excluded_count", "kept_count", "snoozed_count", "impressions", "clicks", "cost_micros", "cost", "conversions", "conversions_value", "similarity_threshold", "max_terms", "ai_model", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "advertising_channel_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recommended_action": { "type": "string" }, "status": { "type": "string" }, "representative_terms": { "type": "array", "items": { "type": "string" } }, "term_count": { "type": "number" }, "unreviewed_count": { "type": "number" }, "excluded_count": { "type": "number" }, "kept_count": { "type": "number" }, "snoozed_count": { "type": "number" }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "cost_micros": { "type": "number" }, "cost": { "type": "number" }, "conversions": { "type": "number" }, "conversions_value": { "type": "number" }, "similarity_threshold": { "type": "number" }, "max_terms": { "type": "number" }, "ai_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v1/google/search-term-buckets/{id}/terms": { "get": { "operationId": "listGoogleSearchTermBucketTerms", "summary": "List terms inside a Google Ads search-term bucket", "tags": [ "google" ], "description": "Returns the raw search-term rows assigned to one semantic bucket. Used by the Review drawer before creating a negative-keyword batch.", "parameters": [ { "schema": { "minimum": 1, "maximum": 500, "default": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minimum": 0, "default": 0, "type": "integer" }, "in": "query", "name": "offset", "required": false }, { "schema": { "format": "uuid", "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "customer_id", "source_view", "search_term", "match_type", "review_status", "campaign_id", "campaign_name", "advertising_channel_type", "ad_group_id", "ad_group_name", "clicks", "cost_micros", "conversions", "similarity" ], "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "source_view": { "type": "string" }, "search_term": { "type": "string" }, "match_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "review_status": { "type": "string" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "advertising_channel_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ad_group_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clicks": { "type": "number" }, "cost_micros": { "type": "number" }, "conversions": { "type": "number" }, "similarity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } }, "total": { "type": "number" } } } } } }, "401": { "description": "Unauthorized - missing or invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "post": { "operationId": "assignGoogleSearchTermsToBucket", "summary": "Save Google Ads search terms in a semantic bucket", "tags": [ "google" ], "description": "Manually assigns cached search terms to the given bucket (a term belongs to at most one bucket, so this moves them). Bucket and terms must share session and Google account. When the bucket cannot fit the request the call fails with 409 BUCKET_FULL unless create_overflow is set, in which case continuation buckets (\"