{ "openapi": "3.0.0", "info": { "title": "Adspire API", "version": "0.1" }, "paths": { "/api/ai-credit-usages": { "get": { "tags": [ "AICreditUsage" ], "summary": "List AI credit usage records for the authenticated user", "description": "Get a list of all AI credit usage records for the authenticated user", "operationId": "listAICreditUsages", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AICreditUsage" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/ai-credit-usages": { "get": { "tags": [ "AICreditUsage" ], "summary": "List AI credit usage records for a brand", "description": "Get a list of all AI credit usage records for a specific brand", "operationId": "listBrandAICreditUsages", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AICreditUsage" } } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Brand not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/workspaces/{workspace}/ai-credit-usages": { "get": { "tags": [ "AICreditUsage" ], "summary": "List AI credit usage records for a workspace", "description": "Get a list of all AI credit usage records for a specific workspace", "operationId": "listWorkspaceAICreditUsages", "parameters": [ { "name": "workspace", "in": "path", "description": "Workspace ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AICreditUsage" } } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Workspace not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/ai-credit-usages/{id}": { "get": { "tags": [ "AICreditUsage" ], "summary": "Get specific AI credit usage record", "description": "Get a specific AI credit usage record by ID", "operationId": "getAICreditUsage", "parameters": [ { "name": "id", "in": "path", "description": "AICreditUsage ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AICreditUsage" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/activity-logs": { "get": { "tags": [ "Activity" ], "summary": "List recent user activity", "description": "Retrieve the authenticated user's recent activity within the active workspace, newest first.", "operationId": "listUserActivity", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated list of the user's activity", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityLog" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "No active workspace set" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboards/{whiteboard}/activity": { "get": { "tags": [ "Activity" ], "summary": "List whiteboard activity", "description": "Retrieve activity for the whiteboard's campaign, newest first.", "operationId": "listWhiteboardActivity", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated list of campaign activity", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityLog" } }, "links": { "type": "object" }, "meta": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/connector-installations/{connectorInstallation}/activity": { "get": { "tags": [ "Activity" ], "summary": "List connector installation activity", "description": "Retrieve publish delivery events for a connector installation, including payload and response debug details.", "operationId": "listConnectorInstallationActivity", "parameters": [ { "name": "connectorInstallation", "in": "path", "description": "Connector installation ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of publish activity events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}/assistant/generate": { "post": { "tags": [ "WhiteboardPostAssistant" ], "summary": "Generate whiteboard post content from a selected prompt", "description": "Synchronously generates post content from provided content using a selected saved brand content prompt and returns the generated content without updating the whiteboard post.", "operationId": "generateWhiteboardPostContentFromPrompt", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPostGenerateFromPromptRequest" } } } }, "responses": { "200": { "description": "Generated post content", "content": { "application/json": { "schema": { "properties": { "generated_content": { "type": "string", "example": "Generated post content tailored from the selected prompt." } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "402": { "description": "Remaining AI credits in the current billing period are below the minimum balance required for this action" }, "403": { "description": "Forbidden" }, "404": { "description": "Post or prompt not found" }, "422": { "description": "Validation error" }, "502": { "description": "AI generation failed" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}/assistant/repurpose": { "post": { "tags": [ "WhiteboardPostAssistant" ], "summary": "Repurpose a whiteboard post onto another brand channel", "description": "Creates a post generation and dispatches an async job that generates post content from the provided source content using a selected saved brand content prompt, adapted for the selected target brand channel, and persists it as a new draft post placed immediately after the source post. The post is created asynchronously, so it does not appear in the response: track the returned generation through the pending generations returned by the whiteboard and whiteboard posts endpoints.", "operationId": "repurposeWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPostRepurposeRequest" } } } }, "responses": { "201": { "description": "Post generation created and repurpose job dispatched", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PostGeneration" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "402": { "description": "Remaining AI credits in the current billing period are below the minimum balance required for this action" }, "403": { "description": "Forbidden" }, "404": { "description": "Post or prompt not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/api-keys": { "get": { "tags": [ "ApiKeys" ], "summary": "List your API keys", "description": "Retrieve all API key records for the authenticated user.", "operationId": "listApiKeys", "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeys" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "ApiKeys" ], "summary": "Create an API key", "description": "Generate a new API key", "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "422": { "description": "Validation error" } } } }, "/api/api-keys/{id}": { "get": { "tags": [ "ApiKeys" ], "summary": "Get an API key", "description": "Retrieve a specific API key", "operationId": "getApiKey", "parameters": [ { "name": "id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "ApiKeys" ], "summary": "Update an API key", "description": "Update a specific API key's information", "operationId": "updateApiKey", "parameters": [ { "name": "id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "ApiKeys" ], "summary": "Delete an API key", "description": "Remove a specific API key", "operationId": "deleteApiKey", "parameters": [ { "name": "id", "in": "path", "description": "API key ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "API key deleted" }, "404": { "description": "Not found" } } } }, "/api/approval-requests": { "get": { "tags": [ "ApprovalRequests" ], "summary": "List approval requests", "description": "Retrieve all approval request records", "operationId": "listApprovalRequests", "responses": { "200": { "description": "List of approval requests", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequests" } } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "No active workspace set" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboard-previews/{whiteboard_preview}/approval-requests": { "get": { "tags": [ "ApprovalRequests" ], "summary": "List approval requests for a specific whiteboard preview in active workspace", "operationId": "listApprovalRequestsByWhiteboardPreview", "parameters": [ { "name": "whiteboard_preview", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of approval requests", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequests" } } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "No active workspace set" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "ApprovalRequests" ], "summary": "Assign approver to whiteboard preview", "description": "Create or resend an approval request for an internal user, existing external user, or new external invite.", "operationId": "createWhiteboardPreviewApprovalRequest", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviewApprovalRequestStoreRequest" } } } }, "responses": { "200": { "description": "Existing pending approval request resent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequests" } } } }, "201": { "description": "Approval request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequests" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Whiteboard preview or approver not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboard-previews/{whiteboard_preview}/approval-request-candidates": { "get": { "tags": [ "ApprovalRequests" ], "summary": "List approval request candidates", "description": "Search internal workspace users and existing external users for a whiteboard preview.", "operationId": "listWhiteboardPreviewApprovalRequestCandidates", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search text or email", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of approval request candidates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequestCandidate" } } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Whiteboard preview not found" }, "422": { "description": "No active workspace set" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/approval-requests/{approval_request}/respond": { "patch": { "tags": [ "ApprovalRequests" ], "summary": "Respond to approval request", "description": "Approve or reject an approval request as the internal approver using bearer auth, or as the external approver using ADSPR-EXTERNAL-TOKEN.", "operationId": "respondToApprovalRequest", "parameters": [ { "name": "approval_request", "in": "path", "description": "Approval Request ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequestRespondRequest" } } } }, "responses": { "200": { "description": "Approval request response saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequests" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Approval request not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] }, { "ExternalAccess": [] } ] } }, "/api/approval-requests/{approval_request}/resend": { "post": { "tags": [ "ApprovalRequests" ], "summary": "Resend approval request email", "description": "Resend the approval request notification email to the assigned approver.", "operationId": "resendApprovalRequest", "parameters": [ { "name": "approval_request", "in": "path", "description": "Approval Request ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approval request email resent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequests" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Approval request not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register a new user", "description": "Creates a new user account and returns authentication token or success message", "operationId": "registerUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "example": "Nikola Cirkovic" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "strongPassword123" }, "workspace_name": { "description": "Required when registering without an invite token", "type": "string", "example": "My Workspace" }, "invite_token": { "description": "Optional invitation token for joining an existing workspace", "type": "string", "example": "a1b2c3d4e5f6...", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "User successfully registered", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User registered successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Nikola Cirkovic" }, "email": { "type": "string", "example": "user@example.com" }, "workspace_name": { "type": "string", "example": "My Workspace" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [] } }, "/api/auth/login": { "post": { "tags": [ "Public", "Auth" ], "summary": "User login", "description": "Logs in a user and returns an access token", "operationId": "loginUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "password123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string", "example": "eyJ0eXAiOiJK..." }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } } } }, "401": { "description": "Invalid credentials" }, "422": { "description": "Validation error" } }, "security": [] } }, "/api/auth/me/": { "get": { "tags": [ "Public", "Auth" ], "summary": "Me request", "description": "Returns me data", "operationId": "getMe", "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Resource Not Found" } } } }, "/api/auth/logout": { "post": { "tags": [ "Public", "Auth" ], "summary": "Log out the authenticated user", "description": "Invalidates the user's token and logs them out", "operationId": "logoutUser", "responses": { "200": { "description": "Successfully logged out", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Successfully logged out" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh JWT token", "description": "Refreshes the current JWT token and returns a new one", "operationId": "refreshToken", "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string", "example": "eyJ0eXAiOiJK..." }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/auth/password/email": { "post": { "tags": [ "Auth" ], "summary": "Send password reset link", "description": "Sends a password reset link when the email belongs to an account. Returns the same success response for unknown or throttled email addresses.", "operationId": "sendResetLinkEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPasswordResetLinkRequest" } } } }, "responses": { "200": { "description": "Password reset request accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "If an account exists, a password reset link has been sent." } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "email": [ "The email field is required." ] } } }, "type": "object" } } } } }, "security": [] } }, "/api/auth/password/reset": { "post": { "tags": [ "Auth" ], "summary": "Reset user password", "description": "Resets the user's password using a valid reset token.", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "Password has been reset", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password has been reset" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error or invalid token", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "This password reset token is invalid." }, "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "example": { "password": [ "The password field is required." ] } } }, "type": "object" } } } } }, "security": [] } }, "/api/backoffice/analytics": { "get": { "tags": [ "Backoffice" ], "summary": "Created records per week/month across all workspaces (Adspire admins only)", "description": "Series for brands, campaigns, approvals, users (workspace memberships), tokens (credits spent) and outgoing n8n webhooks, plus per-workspace totals over the range.", "operationId": "8e4f5a055bd83dc9d002943dace1f957", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "default": "month", "enum": [ "week", "month" ] } }, { "name": "periods", "in": "query", "required": false, "schema": { "type": "integer", "default": 12, "maximum": 52, "minimum": 1 } } ], "responses": { "200": { "description": "Analytics", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "period": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "string", "format": "date" } }, "totals": { "description": "metric name => array of counts aligned with buckets", "type": "object" }, "workspaces": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "totals": { "type": "object" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/workspaces/{workspace}/analytics": { "get": { "tags": [ "Backoffice" ], "summary": "Created records per week/month for one workspace (Adspire admins only)", "operationId": "ae4f8e8328535fd3df7e1641cf41845a", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "default": "month", "enum": [ "week", "month" ] } }, { "name": "periods", "in": "query", "required": false, "schema": { "type": "integer", "default": 12, "maximum": 52, "minimum": 1 } } ], "responses": { "200": { "description": "Analytics (same shape as the global endpoint)" }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/approvals": { "get": { "tags": [ "Backoffice" ], "summary": "Approval requests across all workspaces (Adspire admins only)", "description": "Shows status, due date and whether the approver was sent the request and viewed it. Tokens are never returned.", "operationId": "a83ec5a26db78049790c3f011e3e174a", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApprovalRequestStatus" } }, { "name": "overdue", "in": "query", "description": "Only pending requests past their due date", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated approvals", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackofficeApproval" } } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/workspaces/{workspace}/approvals": { "get": { "tags": [ "Backoffice" ], "summary": "Approval requests of one workspace (Adspire admins only)", "operationId": "08ef741029d99d85b8a29225a683debb", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApprovalRequestStatus" } }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated approvals (same shape as the global endpoint)" }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/connector-definitions": { "get": { "tags": [ "Backoffice" ], "summary": "List connector definitions, optionally by review status (Adspire admins only)", "operationId": "listBackofficeConnectorDefinitions", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated connector definitions", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackofficeConnectorDefinition" } } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/connector-definitions/{slug}/approve": { "post": { "tags": [ "Backoffice" ], "summary": "Approve a connector definition so it is listed for all workspaces (Adspire admins only)", "operationId": "approveConnectorDefinition", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Definition approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackofficeConnectorDefinition" } } } }, "403": { "description": "Not an Adspire admin" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/dashboard": { "get": { "tags": [ "Backoffice" ], "summary": "Dashboard overview: token spend, plan distribution, cancellations (Adspire admins only)", "operationId": "86dcf66779206345609c42bccfdda9b6", "responses": { "200": { "description": "Dashboard data", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "tokens": { "properties": { "spent_30d": { "type": "integer" }, "top_workspaces": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "integer" } }, "type": "object" } } }, "type": "object" }, "plans": { "properties": { "distribution": { "description": "trial, brand, agency, pro, other => workspace count", "type": "object" }, "trials_expiring_soon": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "owner_email": { "type": "string", "nullable": true }, "trial_ends_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" }, "cancellations": { "properties": { "total": { "type": "integer" }, "in_grace_period": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "owner_email": { "type": "string", "nullable": true }, "plan": { "type": "string" }, "ends_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/publishing-issues": { "get": { "tags": [ "Backoffice" ], "summary": "Posts that failed to publish or are overdue (Adspire admins only)", "description": "Posts with status error, or scheduled posts whose post_date passed more than 15 minutes ago, with their failed publish webhook events.", "operationId": "48abb84c5e0caa4c51b62d91166ac409", "parameters": [ { "name": "issue", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "error", "overdue" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated issues", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackofficePublishingIssue" } } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/stats": { "get": { "tags": [ "Backoffice" ], "summary": "Platform-wide stats (Adspire admins only)", "operationId": "983cd713a98f746f4576c31a426eeb4d", "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "users_total": { "type": "integer" }, "users_active_30d": { "type": "integer" }, "users_new_30d": { "type": "integer" }, "workspaces_total": { "type": "integer" }, "brands_total": { "type": "integer" }, "signups_by_month": { "type": "array", "items": { "properties": { "month": { "type": "string", "example": "2026-01" }, "count": { "type": "integer" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/system-prompts": { "get": { "tags": [ "BackofficeSystemPrompts" ], "summary": "List system prompts (Adspire admins only)", "description": "List all system prompts, oldest first, optionally filtered by industry group", "operationId": "listBackofficeSystemPrompts", "parameters": [ { "name": "industry_group", "in": "query", "description": "Only return system prompts of this industry group", "required": false, "schema": { "$ref": "#/components/schemas/IndustryGroup" } } ], "responses": { "200": { "description": "System prompts", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandPrompt" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "BackofficeSystemPrompts" ], "summary": "Create system prompt (Adspire admins only)", "description": "Create a read-only content prompt shown to every brand of the given industry group, or to all brands when the group is null", "operationId": "createBackofficeSystemPrompt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptStoreRequest" } } } }, "responses": { "201": { "description": "System prompt created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandPrompt" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/system-prompts/{brand_prompt}": { "get": { "tags": [ "BackofficeSystemPrompts" ], "summary": "Show system prompt (Adspire admins only)", "description": "Retrieve a single system prompt. Brand-owned prompts are not reachable here.", "operationId": "getBackofficeSystemPrompt", "parameters": [ { "name": "brand_prompt", "in": "path", "description": "System prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "System prompt", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandPrompt" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an Adspire admin" }, "404": { "description": "System prompt not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "System prompt not found" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "BackofficeSystemPrompts" ], "summary": "Update system prompt (Adspire admins only)", "description": "Update the title, content or industry group of a system prompt. Brand-owned prompts are not reachable here.", "operationId": "updateBackofficeSystemPrompt", "parameters": [ { "name": "brand_prompt", "in": "path", "description": "System prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPromptUpdateRequest" } } } }, "responses": { "200": { "description": "System prompt updated", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandPrompt" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not an Adspire admin" }, "404": { "description": "System prompt not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "System prompt not found" } }, "type": "object" } } } }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/users": { "get": { "tags": [ "Backoffice" ], "summary": "List all users (Adspire admins only)", "operationId": "26b848d6174f18027d0bedfe4fecc022", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated users", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackofficeUser" } } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/workspaces": { "get": { "tags": [ "Backoffice" ], "summary": "List all workspaces (Adspire admins only)", "operationId": "b5fc19b4ef3a784556d8097afe8e14fe", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Paginated workspaces", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BackofficeWorkspace" } } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/backoffice/workspaces/{workspace}": { "get": { "tags": [ "Backoffice" ], "summary": "Workspace detail: members, plan, brands, channels, connectors (Adspire admins only)", "operationId": "c5993d64e60278a18e7a623c27e7b145", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BackofficeWorkspaceDetail" } }, "type": "object" } } } }, "403": { "description": "Not an Adspire admin" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/resume_plan": { "post": { "tags": [ "Billing" ], "summary": "Resume subscription", "description": "Resume a cancelled subscription during grace period", "operationId": "resumeSubscription", "responses": { "200": { "description": "Subscription resume result", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/client_portal": { "post": { "tags": [ "Billing" ], "summary": "Get customer portal URL", "description": "Get LemonSqueezy customer portal URL for updating payment information", "operationId": "getClientPortalUrl", "responses": { "200": { "description": "Customer portal URL", "content": { "application/json": { "schema": { "type": "string" }, "example": "https://adspire.lemonsqueezy.com/billing/..." } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" }, "422": { "description": "No active subscription", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "You are not a LemonSqueezy customer" }, "errors": { "properties": { "plan": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/cancel_plan": { "post": { "tags": [ "Billing" ], "summary": "Cancel subscription", "description": "Cancel the current active subscription", "operationId": "cancelSubscription", "responses": { "200": { "description": "Subscription cancelled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Plan is cancelled" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" }, "422": { "description": "No active subscription", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "You are not part of any plan" }, "errors": { "properties": { "plan": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/get_plan": { "post": { "tags": [ "Billing" ], "summary": "Select or switch subscription plan", "description": "Subscribe to a new plan or switch existing subscription. Returns checkout URL for new subscriptions or switches the plan immediately for existing subscribers.", "operationId": "selectPlan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectPlanRequest" } } } }, "responses": { "200": { "description": "Checkout URL or plan switch confirmation", "content": { "application/json": { "schema": { "oneOf": [ { "type": "string", "example": "https://adspire.lemonsqueezy.com/checkout/..." }, { "properties": { "message": { "type": "string", "example": "Plan is switched" } }, "type": "object" } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" }, "422": { "description": "Validation error or same plan selected", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "plan": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/top-up-packs": { "get": { "tags": [ "Billing" ], "summary": "List AI credit top-up packs", "description": "One-time AI credit packs available for purchase, ordered by size. Top-up credits never expire and are spent after the monthly plan credits.", "operationId": "listTopUpPacks", "responses": { "200": { "description": "Available top-up packs", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TopUpPack" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/billing/top-up": { "post": { "tags": [ "Billing" ], "summary": "Start an AI credit top-up checkout", "description": "Creates a Lemon Squeezy checkout for a one-time AI credit pack for the active workspace. Only workspaces with an active subscription can buy credits. Credits are added once Lemon Squeezy reports the order as paid.", "operationId": "createTopUpCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpCheckoutRequest" } } } }, "responses": { "200": { "description": "Checkout URL", "content": { "application/json": { "schema": { "properties": { "checkout_url": { "type": "string", "example": "https://adspire.lemonsqueezy.com/checkout/..." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "No active workspace or user is not the workspace owner" }, "422": { "description": "Unknown top-up pack, or the workspace has no active subscription", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The selected variant id is invalid." }, "errors": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/assets": { "get": { "tags": [ "Public", "BrandAssets" ], "summary": "Get brand assets", "description": "Retrieve the assets (color scheme, typography, media) for a specific brand", "operationId": "getBrandAssets", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand assets retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandAsset" } } } }, "403": { "description": "Forbidden - Brand belongs to different workspace" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Public", "BrandAssets" ], "summary": "Update brand assets", "description": "Update the assets (color scheme, typography) for a specific brand", "operationId": "updateBrandAssets", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandAssetUpdateRequest" } } } }, "responses": { "200": { "description": "Brand assets updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandAsset" } } } }, "403": { "description": "Forbidden - Brand belongs to different workspace" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/channels": { "get": { "tags": [ "Public", "BrandChannels" ], "summary": "List channels for a brand", "description": "Retrieve all channels for a specific brand", "operationId": "listBrandChannels", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of brand channels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandChannel" } } } } }, "403": { "description": "Forbidden - Brand belongs to different workspace" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Public", "BrandChannels" ], "summary": "Sync brand channels", "description": "Sync channels for a brand. Existing channels are updated when an id is provided; omitted unused channels are deleted.", "operationId": "syncBrandChannels", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandChannelUpdateRequest" } } } }, "responses": { "200": { "description": "Brand channels synced", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandChannel" } } } } }, "403": { "description": "Forbidden - Brand belongs to different workspace" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/competitors": { "get": { "tags": [ "Public", "BrandCompetitors" ], "summary": "List competitors for a brand", "description": "Returns every competitor of the brand with its social profiles, oldest first.", "operationId": "listBrandCompetitors", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of brand competitors", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandCompetitor" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Brand belongs to a different workspace" }, "404": { "description": "Brand not found" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Public", "BrandCompetitors" ], "summary": "Create brand competitor", "description": "Creates a competitor for the brand together with its social profiles. At least one profile is required.", "operationId": "createBrandCompetitor", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCompetitorStoreRequest" } } } }, "responses": { "201": { "description": "Brand competitor created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandCompetitor" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to update this brand" }, "404": { "description": "Brand not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/competitors/{brand_competitor}": { "get": { "tags": [ "Public", "BrandCompetitors" ], "summary": "Show brand competitor", "description": "Returns one competitor of the brand with its social profiles.", "operationId": "getBrandCompetitor", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_competitor", "in": "path", "description": "Brand competitor ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand competitor details", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandCompetitor" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Brand belongs to a different workspace" }, "404": { "description": "Brand or competitor not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Public", "BrandCompetitors" ], "summary": "Update brand competitor", "description": "Replaces the competitor's details and syncs its social profiles. Optional fields left out are cleared. Profiles sent with an id are updated, profiles without one are added, and profiles left out are deleted.", "operationId": "updateBrandCompetitor", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_competitor", "in": "path", "description": "Brand competitor ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandCompetitorUpdateRequest" } } } }, "responses": { "200": { "description": "Brand competitor updated", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandCompetitor" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to update this brand" }, "404": { "description": "Brand or competitor not found" }, "422": { "description": "Validation error, or a kept profile no longer exists" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Public", "BrandCompetitors" ], "summary": "Delete brand competitor", "description": "Deletes the competitor together with its social profiles and collected signals.", "operationId": "deleteBrandCompetitor", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_competitor", "in": "path", "description": "Brand competitor ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Brand competitor deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to delete from this brand" }, "404": { "description": "Brand or competitor not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands": { "get": { "tags": [ "Public", "Brands" ], "summary": "List brands", "description": "Retrieve all brand records for the authenticated user's active workspace", "operationId": "listBrands", "responses": { "200": { "description": "List of brands", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brands" } } } } }, "422": { "description": "User does not have an active workspace", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No active workspace set." } }, "type": "object" } } } } } }, "post": { "tags": [ "Public", "Brands" ], "summary": "Create brand", "description": "Create a new brand record", "operationId": "createBrand", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "company_id" ], "properties": { "company_id": { "type": "string", "example": "sqid2" }, "name": { "type": "string", "example": "Acme Corp", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "contact@acme.com" }, "address": { "type": "string", "example": "123 Main St", "nullable": true, "maxLength": 255 }, "city": { "type": "string", "example": "New York", "nullable": true, "maxLength": 100 }, "telephone": { "type": "string", "example": "+1234567890", "nullable": true, "maxLength": 30 }, "website": { "type": "string", "example": "https://acme.com", "nullable": true }, "contact": { "type": "string", "example": "John Doe", "nullable": true }, "notes": { "type": "string", "example": "Important client", "nullable": true }, "selected_country": { "type": "string", "example": "US", "nullable": true }, "selected_industry": { "type": "string", "example": "Technology", "nullable": true }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group used to pick system prompts, null means General" } }, "type": "object" } } } }, "responses": { "201": { "description": "Brand created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brands" } } } }, "422": { "description": "Validation error or no active workspace", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The email field is required." } }, "company_id": { "type": "array", "items": { "type": "string", "example": "The company id field is required." } } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/brands/from-website": { "post": { "tags": [ "Brands" ], "summary": "Create a brand from a website URL", "description": "Immediately creates a brand and its company using fallback data derived from the URL (name from the domain, email info@domain), then starts a brand extraction linked to the brand. When the extraction completes, its results are applied to the brand server-side and a notification is sent. If a completed extraction for the same URL exists in the workspace from the last 7 days, it is applied immediately and no new extraction job is dispatched.", "operationId": "createBrandFromWebsite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandFromWebsiteRequest" } } } }, "responses": { "201": { "description": "Brand created and extraction started (or applied from a recent cached extraction)", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "brand": { "$ref": "#/components/schemas/Brands" }, "extraction": { "$ref": "#/components/schemas/BrandExtraction" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "description": "Remaining AI credits in the current billing period are below the minimum balance required for this action" }, "422": { "description": "Validation error or no active workspace", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No active workspace set." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{id}": { "get": { "tags": [ "Public", "Brands" ], "summary": "Show brand", "description": "Retrieve a specific brand by id", "operationId": "getBrand", "parameters": [ { "name": "id", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brands" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "Brands" ], "summary": "Update brand", "description": "Update an existing brand record", "operationId": "updateBrand", "parameters": [ { "name": "id", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "company_id": { "type": "string", "example": "sqid2" }, "name": { "type": "string", "example": "Acme Corp", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "contact@acme.com" }, "address": { "type": "string", "example": "123 Main St", "nullable": true, "maxLength": 255 }, "city": { "type": "string", "example": "New York", "nullable": true, "maxLength": 100 }, "telephone": { "type": "string", "example": "+1234567890", "nullable": true, "maxLength": 30 }, "website": { "type": "string", "example": "https://acme.com", "nullable": true }, "contact": { "type": "string", "example": "John Doe", "nullable": true }, "notes": { "type": "string", "example": "Important client", "nullable": true }, "selected_country": { "type": "string", "example": "US", "nullable": true }, "selected_industry": { "type": "string", "example": "Technology", "nullable": true }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group used to pick system prompts, null means General" } }, "type": "object" } } } }, "responses": { "200": { "description": "Brand updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brands" } } } }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "email": { "type": "array", "items": { "type": "string", "example": "The email has already been taken." } } }, "type": "object" } }, "type": "object" } } } } } }, "delete": { "tags": [ "Public", "Brands" ], "summary": "Delete brand", "description": "Delete a specific brand record", "operationId": "deleteBrand", "parameters": [ { "name": "id", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Brand deleted" }, "404": { "description": "Not found" } } } }, "/api/brand-extractions": { "post": { "tags": [ "BrandExtractions" ], "summary": "Start a brand extraction", "description": "Dispatches an async job that crawls the given website URL and extracts company information and brand assets (colors, typography, logo). Poll the show endpoint for the result. If a completed extraction for the same URL exists in the workspace from the last 7 days, it is returned directly instead of dispatching a new job, unless force is set to true.", "operationId": "createBrandExtraction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandExtractionStoreRequest" } } } }, "responses": { "200": { "description": "Recent completed extraction for this URL reused, no new job dispatched", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandExtraction" } }, "type": "object" } } } }, "201": { "description": "Brand extraction created and job dispatched", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandExtraction" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "description": "Remaining AI credits in the current billing period are below the minimum balance required for this action" }, "422": { "description": "Validation error or no active workspace", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No active workspace set." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brand-extractions/{id}": { "get": { "tags": [ "BrandExtractions" ], "summary": "Get a brand extraction", "description": "Retrieve a brand extraction with its status and, once completed, the extracted company information and brand assets", "operationId": "getBrandExtraction", "parameters": [ { "name": "id", "in": "path", "description": "Sqid of the brand extraction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand extraction", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandExtraction" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Brand extraction belongs to another workspace" }, "404": { "description": "Brand extraction not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/graph": { "get": { "tags": [ "Public", "Brands", "BrandGraph" ], "summary": "Get brand graph", "description": "Retrieve the knowledge graph of a brand, grouped into company info, brand identity, offerings and social proof", "operationId": "getBrandGraph", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand graph retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandGraph" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Brand belongs to different workspace" }, "404": { "description": "Brand has no graph" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/graph/{group}": { "put": { "tags": [ "Public", "Brands", "BrandGraph" ], "summary": "Update a brand graph group", "description": "Validate a full brand graph group sent by the client and hand it over for asynchronous processing. The update is published to the brand graph stream and applied by the graph consumer, so the change is not visible immediately.", "operationId": "updateBrandGraphGroup", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "group", "in": "path", "description": "Brand graph group to update", "required": true, "schema": { "$ref": "#/components/schemas/BrandGraphGroup" } } ], "requestBody": { "description": "The whole group object, matching the group given in the path", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpdateBrandGraphCompanyInfoRequest" }, { "$ref": "#/components/schemas/UpdateBrandGraphBrandIdentityRequest" }, { "$ref": "#/components/schemas/UpdateBrandGraphOfferingsRequest" }, { "$ref": "#/components/schemas/UpdateBrandGraphSocialProofRequest" } ] } } } }, "responses": { "202": { "description": "Brand graph group update accepted for processing", "content": { "application/json": { "schema": { "properties": { "group": { "$ref": "#/components/schemas/BrandGraphGroup" }, "uuid": { "description": "Message uuid published to the brand graph stream, use it to correlate the update", "type": "string", "format": "uuid", "example": "1c2f6f0e-9f3a-4f7d-8f2b-5a1c9d6e4b31" }, "data": { "description": "The accepted group payload", "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Brand belongs to different workspace" }, "404": { "description": "Brand not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/prompts": { "get": { "tags": [ "Public", "BrandPrompts" ], "summary": "List prompts for a brand", "description": "Retrieve the brand's own prompts followed by the read-only system prompts visible to it (General plus the brand's industry group), with optional type filter", "operationId": "listBrandPrompts", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by prompt type", "required": false, "schema": { "$ref": "#/components/schemas/BrandPromptType" } } ], "responses": { "200": { "description": "List of brand prompts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrandPrompt" } } } } }, "403": { "description": "Forbidden - Brand belongs to different workspace" } } }, "post": { "tags": [ "Public", "BrandPrompts" ], "summary": "Create brand prompt", "description": "Create a new prompt for a brand", "operationId": "createBrandPrompt", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPromptStoreRequest" } } } }, "responses": { "201": { "description": "Brand prompt created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPrompt" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/brands/{brand}/prompts/{brand_prompt}": { "get": { "tags": [ "Public", "BrandPrompts" ], "summary": "Show brand prompt", "description": "Retrieve a prompt owned by the brand or a system prompt visible to it", "operationId": "getBrandPrompt", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_prompt", "in": "path", "description": "Brand Prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand prompt details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPrompt" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "BrandPrompts" ], "summary": "Update brand prompt", "description": "Update an existing brand prompt", "operationId": "updateBrandPrompt", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_prompt", "in": "path", "description": "Brand Prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPromptUpdateRequest" } } } }, "responses": { "200": { "description": "Brand prompt updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandPrompt" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "BrandPrompts" ], "summary": "Delete brand prompt", "description": "Delete a specific brand prompt", "operationId": "deleteBrandPrompt", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_prompt", "in": "path", "description": "Brand Prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Brand prompt deleted" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/brands/{brand}/prompts/{brand_prompt}/duplicate": { "post": { "tags": [ "Public", "BrandPrompts" ], "summary": "Duplicate system prompt into brand", "description": "Copy a read-only system prompt visible to the brand into a new editable content prompt owned by the brand", "operationId": "duplicateBrandPrompt", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID (sqid)", "required": true, "schema": { "type": "string" } }, { "name": "brand_prompt", "in": "path", "description": "System prompt ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Brand prompt created from the system prompt", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandPrompt" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "System prompt not found for this brand", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Prompt not found for this brand" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/settings": { "get": { "tags": [ "BrandSettings" ], "summary": "Get brand settings", "description": "Returns the voice settings and logo of the given brand.", "operationId": "getBrandSettings", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand settings retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandSetting" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to view this brand" }, "404": { "description": "Brand not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "BrandSettings" ], "summary": "Update brand settings", "description": "Updates the voice settings of the given brand. Only the provided fields are changed. Changing hard_constraints is mirrored to the brand graph, where the value is read only.", "operationId": "updateBrandSettings", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Brand settings updated", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandSetting" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to update this brand" }, "404": { "description": "Brand not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/signal-snapshots/latest": { "get": { "tags": [ "BrandSignals" ], "summary": "Get the latest brand signal snapshot", "description": "Returns the latest stored daily snapshot of brand and competitor signals for the given brand. If no snapshot exists yet, one is captured on demand for the current day and returned.", "operationId": "getLatestBrandSignalSnapshot", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest brand signal snapshot retrieved", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BrandSignalDailySnapshot" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not allowed to view this brand" }, "404": { "description": "Brand not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/campaigns": { "get": { "tags": [ "Public", "Campaigns" ], "summary": "List campaigns by workspace", "description": "Get a list of all campaigns for the authenticated user's active workspace. Optionally filter by status and/or completion state.", "operationId": "listCampaigns", "parameters": [ { "name": "status", "in": "query", "description": "Filter campaigns by status", "required": false, "schema": { "$ref": "#/components/schemas/CampaignStatus" } }, { "name": "completed", "in": "query", "description": "Filter by completion state based on end_date. true = end_date in the past, false = end_date is null or in the future.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignListItems" } } } } }, "422": { "description": "User does not have an active workspace, or the provided status value is invalid.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User must have an active workspace" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Public", "Campaigns" ], "summary": "Create campaign", "description": "Create a new campaign", "operationId": "createCampaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStoreRequest" } } } }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaigns" } } } }, "422": { "description": "Validation error" } } } }, "/api/brands/{brand}/campaigns": { "get": { "tags": [ "Public", "Campaigns" ], "summary": "List campaigns for a brand", "description": "Get a list of all campaigns for a specific brand.", "operationId": "listBrandCampaigns", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Campaigns" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/campaigns/{id}": { "get": { "tags": [ "Public", "Campaigns" ], "summary": "Get campaign", "description": "Get a specific campaign", "operationId": "getCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaigns" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "Campaigns" ], "summary": "Update campaign", "description": "Update a campaign", "operationId": "updateCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdateRequest" } } } }, "responses": { "200": { "description": "Campaign updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaigns" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "Campaigns" ], "summary": "Delete campaign", "description": "Delete a campaign", "operationId": "deleteCampaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Campaign deleted" }, "404": { "description": "Not found" } } } }, "/api/companies": { "get": { "tags": [ "Public", "Companies" ], "summary": "List companies", "description": "Retrieve all companies for the authenticated user", "operationId": "listCompanies", "responses": { "200": { "description": "List of companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Companies" } } } } } } }, "post": { "tags": [ "Public", "Companies" ], "summary": "Create company", "description": "Create a new company record", "operationId": "createCompany", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Acme Corp" }, "address": { "type": "string", "example": "123 Main St", "nullable": true }, "email": { "type": "string", "format": "email", "example": "contact@acme.com", "nullable": true }, "phone": { "type": "string", "example": "+1234567890", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Company created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" } } } }, "422": { "description": "Validation error" } } } }, "/api/companies/autocomplete": { "get": { "tags": [ "Public", "Companies" ], "summary": "Autocomplete companies", "description": "Search companies by name for autocomplete functionality", "operationId": "autocompleteCompanies", "parameters": [ { "name": "search", "in": "query", "description": "Search term to filter companies by name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of matching companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Companies" } } } } } } } }, "/api/companies/{id}": { "get": { "tags": [ "Public", "Companies" ], "summary": "Show company", "description": "Retrieve a specific company by id", "operationId": "getCompany", "parameters": [ { "name": "id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "Companies" ], "summary": "Update company", "description": "Update an existing company record", "operationId": "updateCompany", "parameters": [ { "name": "id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Acme Corp" }, "address": { "type": "string", "example": "123 Main St", "nullable": true }, "email": { "type": "string", "format": "email", "example": "contact@acme.com", "nullable": true }, "phone": { "type": "string", "example": "+1234567890", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "Companies" ], "summary": "Delete company", "description": "Delete a specific company record", "operationId": "deleteCompany", "parameters": [ { "name": "id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Company deleted" }, "404": { "description": "Not found" } } } }, "/api/connectors": { "get": { "tags": [ "Connectors" ], "summary": "List connectors", "description": "Retrieve all active connector records with optional filters", "operationId": "listConnectors", "parameters": [ { "name": "verified", "in": "query", "description": "Filter by verification status", "required": false, "schema": { "type": "boolean" } }, { "name": "featured", "in": "query", "description": "Filter by featured status", "required": false, "schema": { "type": "boolean" } }, { "name": "pricing_model", "in": "query", "description": "Filter by pricing model", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of connectors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } } } }, "422": { "description": "No active workspace set", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No active workspace set." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/connector-installations": { "get": { "tags": [ "ConnectorInstallations" ], "summary": "List connector installations", "description": "Retrieve all connector installations for the authenticated user's active workspace", "operationId": "listConnectorInstallations", "parameters": [ { "name": "brand_id", "in": "query", "description": "Filter by brand", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by installation status", "required": false, "schema": { "$ref": "#/components/schemas/ConnectorInstallationStatus" } } ], "responses": { "200": { "description": "List of connector installations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorInstallation" } } } } }, "422": { "description": "No active workspace set", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No active workspace set." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "ConnectorInstallations" ], "summary": "Create connector installation", "description": "Create a new connector installation record", "operationId": "createConnectorInstallation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationStoreRequest" } } } }, "responses": { "201": { "description": "Connector installation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallation" } } } }, "400": { "description": "Connector already installed for this brand", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "This connector is already installed for this brand." } }, "type": "object" } } } }, "422": { "description": "Validation error or no active workspace", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "connector_id": { "type": "array", "items": { "type": "string", "example": "The connector id field is required." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/connector-installations/{id}": { "put": { "tags": [ "ConnectorInstallations" ], "summary": "Update connector installation", "description": "Update an existing connector installation record", "operationId": "updateConnectorInstallation", "parameters": [ { "name": "id", "in": "path", "description": "Connector installation ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallationUpdateRequest" } } } }, "responses": { "200": { "description": "Connector installation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorInstallation" } } } }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Validation failed" }, "errors": { "properties": { "connector_id": { "type": "array", "items": { "type": "string", "example": "The selected connector id is invalid." } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "ConnectorInstallations" ], "summary": "Delete connector installation", "description": "Delete a specific connector installation", "operationId": "deleteConnectorInstallation", "parameters": [ { "name": "id", "in": "path", "description": "Connector installation ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connector installation deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/connector-definitions": { "get": { "tags": [ "Connector Definitions" ], "summary": "List active connector definitions", "operationId": "listConnectorDefinitions", "parameters": [ { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "brand", "workspace" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "post_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of connector definitions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Connector Definitions" ], "summary": "Register a connector definition", "description": "Workspace admins create definitions owned by their workspace and may update only their own; new and edited partner definitions are pending until approved by Adspire staff. Adspire staff may update any definition.", "operationId": "registerConnectorDefinition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "slug", "name", "scope", "store_field", "auth_type", "base_url" ], "properties": { "slug": { "type": "string", "example": "my-connector", "maxLength": 120 }, "name": { "type": "string", "maxLength": 255 }, "manifest_version": { "type": "string", "example": "1.0", "nullable": true }, "scope": { "type": "string", "enum": [ "brand", "workspace" ] }, "store_field": { "type": "string", "enum": [ "store_url", "shop", "none" ] }, "auth_type": { "type": "string", "enum": [ "oauth2", "api_key", "none" ] }, "install_fields": { "type": "array", "items": { "type": "object" }, "nullable": true }, "capabilities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "events": { "type": "array", "items": { "type": "string" }, "nullable": true }, "ui_actions": { "type": "array", "items": { "type": "object" }, "nullable": true }, "is_active": { "type": "boolean", "nullable": true }, "base_url": { "type": "string", "format": "uri" } }, "type": "object" } } } }, "responses": { "201": { "description": "Definition created", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "Definition updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/jobs/crawl-page": { "post": { "tags": [ "Crawl" ], "summary": "Crawl a URL and generate posts", "description": "Dispatches an async job that crawls the given URL, extracts structured content using AI, and generates platform-optimized posts. Returns the created post generation whose status can be tracked through the whiteboard posts index endpoint.", "operationId": "crawlUrl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlURLRequest" } } } }, "responses": { "201": { "description": "Post generation created and crawl job dispatched", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PostGeneration" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "402": { "description": "Remaining AI credits in the current billing period are below the minimum balance required for this action" }, "403": { "description": "Whiteboard belongs to another workspace" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/deployment-event": { "post": { "tags": [ "Deployments" ], "summary": "Record deployment event", "description": "Stores a deployment event. Successful deployments also update the service inventory. Requires the DEPLOYMENT_EVENT_TOKEN as a bearer token.", "operationId": "createDeploymentEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "service", "repo", "environment", "commit", "deployed_at", "status" ], "properties": { "service": { "type": "string", "example": "api" }, "repo": { "type": "string", "example": "my-org/api" }, "environment": { "type": "string", "example": "production" }, "commit": { "type": "string", "example": "abc123" }, "image_sha": { "type": "string", "example": "sha256:xyz", "nullable": true }, "version": { "type": "string", "example": "v1.2.4", "nullable": true }, "deployed_at": { "type": "string", "format": "date-time", "example": "2026-06-04T12:00:00Z" }, "status": { "$ref": "#/components/schemas/DeploymentStatus" } }, "type": "object" } } } }, "responses": { "201": { "description": "Deployment event recorded", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DeploymentEvent" } }, "type": "object" } } } }, "401": { "description": "Missing or invalid deployment token" }, "422": { "description": "Validation error" } } } }, "/api/external/me": { "get": { "tags": [ "External Auth" ], "summary": "Get current external user", "description": "Get the currently authenticated external user based on ADSPR-EXTERNAL-TOKEN", "operationId": "getExternalCurrentUser", "responses": { "200": { "description": "Current external user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "403": { "description": "Invalid or missing token" } }, "security": [ { "ExternalAccess": [] } ] } }, "/api/whiteboard-previews/external/{whiteboard_preview}/comments": { "get": { "tags": [ "WhiteboardPreviewComments" ], "summary": "List comments for a whiteboard preview", "description": "Retrieve the campaign-level comments of every preview version of this whiteboard, including soft-deleted ones. Only versions in the requested preview's own workspace are included. Each comment carries the preview version it was left on, and is_outdated is true for comments left on a different version than the requested one. Use include_posts=true to also include comments on the posts of the requested preview. Supports filtering by commenter type. The commenter filter applies to thread starters, and their replies come along. A reply whose parent is not listed (for example because its version was deleted) is a thread starter.", "operationId": "listWhiteboardPreviewComments", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "commenter_source", "in": "query", "description": "Filter comments by commenter source", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "internal", "external", "mine" ] } }, { "name": "include_posts", "in": "query", "description": "Include comments from all posts within this preview", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of comments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comments" } } } } }, "403": { "description": "Forbidden - No access to this preview" }, "404": { "description": "Not found" } }, "security": [ { "PreviewAccess": [] } ] }, "post": { "tags": [ "WhiteboardPreviewComments" ], "summary": "Create comment", "description": "Create a new comment (or reply) on a whiteboard preview", "operationId": "createWhiteboardPreviewComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviewCommentStoreRequest" } } } }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - No access to this preview" }, "422": { "description": "Validation error" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/whiteboard-previews/external/{whiteboard_preview}/comments/{comment}": { "put": { "tags": [ "WhiteboardPreviewComments" ], "summary": "Update comment", "description": "Update an existing whiteboard preview comment (users can only edit their own comments)", "operationId": "updateWhiteboardPreviewComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviewCommentUpdateRequest" } } } }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - Can only edit own comments or no access to preview" }, "404": { "description": "Comment or preview not found" }, "422": { "description": "Validation error" } }, "security": [ { "PreviewAccess": [] } ] }, "delete": { "tags": [ "WhiteboardPreviewComments" ], "summary": "Delete comment", "description": "Soft delete a whiteboard preview comment (users can only delete their own comments). Returns the deleted comment with is_deleted flag set to true.", "operationId": "deleteWhiteboardPreviewComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - Can only delete own comments or no access to preview" }, "404": { "description": "Comment or preview not found" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/whiteboard-previews/external/{whiteboard_preview}": { "get": { "tags": [ "External Whiteboard Previews" ], "summary": "Get whiteboard preview with posts", "description": "Get whiteboard preview with all posts for external review", "operationId": "showExternalWhiteboardPreview", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard preview with posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviewsWithPosts" } } } }, "404": { "description": "Not found" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/whiteboard-previews/external/{whiteboard_preview}/posts/{whiteboard_preview_post}/comments": { "get": { "tags": [ "WhiteboardPreviewPostComments" ], "summary": "List comments for a whiteboard preview post", "description": "Retrieve all comments (including replies) for a specific whiteboard preview post. Supports filtering by commenter type.", "operationId": "listWhiteboardPreviewPostComments", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_preview_post", "in": "path", "description": "Whiteboard Preview Post ID", "required": true, "schema": { "type": "string" } }, { "name": "commenter_source", "in": "query", "description": "Filter comments by commenter source", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "internal", "external", "mine" ] } } ], "responses": { "200": { "description": "List of comments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comments" } } } } }, "403": { "description": "Forbidden - No access to this preview" }, "404": { "description": "Post not found for this preview" } }, "security": [ { "PreviewAccess": [] } ] }, "post": { "tags": [ "WhiteboardPreviewPostComments" ], "summary": "Create comment", "description": "Create a new comment (or reply) on a whiteboard preview post", "operationId": "createWhiteboardPreviewPostComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_preview_post", "in": "path", "description": "Whiteboard Preview Post ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "content" ], "properties": { "content": { "type": "string", "example": "This is a great post!" }, "parent_id": { "description": "Parent comment ID for replies", "type": "string", "example": "cmt_abc123", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - No access to this preview" }, "404": { "description": "Post not found for this preview" }, "422": { "description": "Validation error" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/whiteboard-previews/external/{whiteboard_preview}/posts/{whiteboard_preview_post}/comments/{comment}": { "put": { "tags": [ "WhiteboardPreviewPostComments" ], "summary": "Update comment", "description": "Update an existing comment (users can only edit their own comments)", "operationId": "updateWhiteboardPreviewPostComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_preview_post", "in": "path", "description": "Whiteboard Preview Post ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "content": { "type": "string", "example": "Updated comment text" } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - Can only edit own comments or no access to preview" }, "404": { "description": "Comment or post not found" }, "422": { "description": "Validation error" } }, "security": [ { "PreviewAccess": [] } ] }, "delete": { "tags": [ "WhiteboardPreviewPostComments" ], "summary": "Delete comment", "description": "Soft delete a comment (users can only delete their own comments). Returns the deleted comment with is_deleted flag set to true.", "operationId": "deleteWhiteboardPreviewPostComment", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_preview_post", "in": "path", "description": "Whiteboard Preview Post ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden - Can only delete own comments or no access to preview" }, "404": { "description": "Comment or post not found" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/external-users": { "get": { "tags": [ "ExternalUsers" ], "summary": "List external users", "description": "Retrieve all external user records", "operationId": "listExternalUsers", "parameters": [ { "name": "brand_id", "in": "query", "description": "Filter by brand ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of external users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalUsers" } } } } }, "422": { "description": "No active workspace set" } } }, "post": { "tags": [ "ExternalUsers" ], "summary": "Create external user", "description": "Create a new external user record", "operationId": "createExternalUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "responses": { "201": { "description": "External user created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "422": { "description": "Validation error" } } } }, "/api/external-users/{id}": { "get": { "tags": [ "ExternalUsers" ], "summary": "Show external user", "description": "Retrieve a specific external user by id", "operationId": "getExternalUser", "parameters": [ { "name": "id", "in": "path", "description": "External User ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "External user details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "ExternalUsers" ], "summary": "Update external user", "description": "Update an existing external user record", "operationId": "updateExternalUser", "parameters": [ { "name": "id", "in": "path", "description": "External User ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "responses": { "200": { "description": "External user updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalUsers" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "ExternalUsers" ], "summary": "Delete external user", "description": "Delete a specific external user", "operationId": "deleteExternalUser", "parameters": [ { "name": "id", "in": "path", "description": "External User ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "External user deleted" }, "404": { "description": "Not found" } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications", "description": "Retrieve notifications for the authenticated user", "operationId": "listNotifications", "parameters": [ { "name": "unread", "in": "query", "description": "Filter for unread notifications only", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of notifications", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notifications" } } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/notifications/{notification}/read": { "patch": { "tags": [ "Notifications" ], "summary": "Mark notification as read", "description": "Mark one notification belonging to the authenticated user as read", "operationId": "markNotificationAsRead", "parameters": [ { "name": "notification", "in": "path", "description": "Notification UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Notification marked as read", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Notifications" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Notification not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/notifications/read-all": { "patch": { "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "description": "Mark all unread notifications belonging to the authenticated user as read", "operationId": "markAllNotificationsAsRead", "responses": { "200": { "description": "Unread notifications marked as read", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "marked_read_count": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/packages": { "get": { "tags": [ "Packages" ], "summary": "List packages", "description": "Retrieve all package records", "operationId": "listPackages", "responses": { "200": { "description": "List of packages", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Packages" } } } } } } }, "post": { "tags": [ "Packages" ], "summary": "Create package", "description": "Create a new package record", "operationId": "createPackage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Packages" } } } }, "responses": { "201": { "description": "Package created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Packages" } } } }, "422": { "description": "Validation error" } } } }, "/api/packages/{id}": { "get": { "tags": [ "Packages" ], "summary": "Show package", "description": "Retrieve a specific package by id", "operationId": "getPackage", "parameters": [ { "name": "id", "in": "path", "description": "Package ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Package details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Packages" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Packages" ], "summary": "Update package", "description": "Update an existing package record", "operationId": "updatePackage", "parameters": [ { "name": "id", "in": "path", "description": "Package ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Packages" } } } }, "responses": { "200": { "description": "Package updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Packages" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Packages" ], "summary": "Delete package", "description": "Delete a specific package", "operationId": "deletePackage", "parameters": [ { "name": "id", "in": "path", "description": "Package ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Package deleted" }, "404": { "description": "Not found" } } } }, "/api/post-generations/{id}/dismiss": { "patch": { "tags": [ "PostGenerations" ], "summary": "Dismiss a failed post generation", "description": "Dismisses a failed post generation so it is no longer returned with the whiteboard as a pending generation. Only failed generations can be dismissed.", "operationId": "dismissPostGeneration", "parameters": [ { "name": "id", "in": "path", "description": "Sqid of the post generation", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Post generation dismissed", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PostGeneration" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Post generation belongs to another workspace" }, "404": { "description": "Post generation not found" }, "422": { "description": "Post generation is not failed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Only failed post generations can be dismissed." } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/brands/{brand}/studio-assets": { "get": { "tags": [ "Public", "StudioAssets" ], "summary": "List studio assets", "description": "Retrieve Characters, Locations and Objects for a brand", "operationId": "listStudioAssets", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by type", "required": false, "schema": { "$ref": "#/components/schemas/StudioAssetType" } } ], "responses": { "200": { "description": "List of studio assets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StudioAssets" } } } } }, "422": { "description": "Invalid type value" } } }, "post": { "tags": [ "Public", "StudioAssets" ], "summary": "Create studio asset", "operationId": "createStudioAsset", "parameters": [ { "name": "brand", "in": "path", "description": "Brand ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioAssetStoreRequest" } } } }, "responses": { "201": { "description": "Asset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioAssets" } } } }, "422": { "description": "Validation error" } } } }, "/api/studio-assets/{studio_asset}": { "get": { "tags": [ "Public", "StudioAssets" ], "summary": "Get studio asset", "operationId": "getStudioAsset", "parameters": [ { "name": "studio_asset", "in": "path", "description": "Studio Asset ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioAssets" } } } }, "403": { "description": "Forbidden" } } }, "put": { "tags": [ "Public", "StudioAssets" ], "summary": "Update studio asset", "operationId": "updateStudioAsset", "parameters": [ { "name": "studio_asset", "in": "path", "description": "Studio Asset ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true, "maxLength": 255 }, "reference_images": { "type": "array", "items": { "type": "string" }, "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Asset updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioAssets" } } } }, "403": { "description": "Forbidden" } } }, "delete": { "tags": [ "Public", "StudioAssets" ], "summary": "Delete studio asset", "operationId": "deleteStudioAsset", "parameters": [ { "name": "studio_asset", "in": "path", "description": "Studio Asset ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Asset deleted" }, "403": { "description": "Forbidden" } } } }, "/api/studio": { "get": { "tags": [ "Public", "Studios" ], "summary": "List studios", "description": "Retrieve studios for the authenticated user's active workspace", "operationId": "listStudios", "parameters": [ { "name": "brand_id", "in": "query", "description": "Filter by brand ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "$ref": "#/components/schemas/StudioStatus" } } ], "responses": { "200": { "description": "List of studios", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StudioListItems" } } } } }, "422": { "description": "No active workspace set, or invalid status value" } } }, "post": { "tags": [ "Public", "Studios" ], "summary": "Create studio", "description": "Create a new studio", "operationId": "createStudio", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioStoreRequest" } } } }, "responses": { "201": { "description": "Studio created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Studios" } } } }, "422": { "description": "No active workspace set, or validation error" } } } }, "/api/studio/{studio}": { "get": { "tags": [ "Public", "Studios" ], "summary": "Get studio", "description": "Retrieve a specific studio with its scenes", "operationId": "getStudio", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Studio details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Studios" } } } }, "403": { "description": "Forbidden" } } }, "put": { "tags": [ "Public", "Studios" ], "summary": "Update studio", "description": "Update an existing studio", "operationId": "updateStudio", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "nullable": true, "maxLength": 255 }, "status": { "oneOf": [ { "$ref": "#/components/schemas/StudioStatus" } ], "nullable": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Studio updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Studios" } } } }, "403": { "description": "Forbidden" } } }, "delete": { "tags": [ "Public", "Studios" ], "summary": "Delete studio", "description": "Delete a specific studio and its scenes", "operationId": "deleteStudio", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Studio deleted" }, "403": { "description": "Forbidden" } } } }, "/api/studio/{studio}/scenes": { "get": { "tags": [ "Public", "StudioScenes" ], "summary": "List scenes for a studio", "operationId": "listStudioScenes", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of studio scenes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StudioScenes" } } } } }, "403": { "description": "Forbidden" } } }, "post": { "tags": [ "Public", "StudioScenes" ], "summary": "Create studio scene", "operationId": "createStudioScene", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioSceneStoreRequest" } } } }, "responses": { "201": { "description": "Scene created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/studio/{studio}/scenes/{scene}": { "get": { "tags": [ "Public", "StudioScenes" ], "summary": "Get studio scene", "operationId": "getStudioScene", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scene details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "StudioScenes" ], "summary": "Update studio scene", "operationId": "updateStudioScene", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioSceneStoreRequest" } } } }, "responses": { "200": { "description": "Scene updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "StudioScenes" ], "summary": "Delete studio scene", "operationId": "deleteStudioScene", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Scene deleted" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/studio/{studio}/scenes/reorder": { "post": { "tags": [ "Public", "StudioScenes" ], "summary": "Reorder studio scenes", "operationId": "reorderStudioScenes", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "scenes" ], "properties": { "scenes": { "type": "array", "items": { "required": [ "id", "order" ], "properties": { "id": { "type": "string", "example": "stsc_abc123" }, "order": { "type": "integer", "example": 0 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Scenes reordered", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StudioScenes" } } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/studio/{studio}/scenes/{scene}/assets": { "post": { "tags": [ "Public", "StudioScenes" ], "summary": "Attach an asset to a scene", "operationId": "attachStudioSceneAsset", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioSceneAttachAssetRequest" } } } }, "responses": { "200": { "description": "Asset attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Asset does not belong to this studio's brand" } } } }, "/api/studio/{studio}/scenes/{scene}/assets/{studio_asset}": { "delete": { "tags": [ "Public", "StudioScenes" ], "summary": "Detach an asset from a scene", "operationId": "detachStudioSceneAsset", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } }, { "name": "studio_asset", "in": "path", "description": "Studio Asset ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Asset detached" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/studio/{studio}/scenes/{scene}/generate-frame": { "post": { "tags": [ "Public", "StudioScenes" ], "summary": "Generate or apply a scene frame", "description": "Records a new frame version. Supplying image_url applies it immediately (upload/replace); supplying only a prompt queues it as pending for later generation.", "operationId": "generateStudioSceneFrame", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioSceneGenerateFrameRequest" } } } }, "responses": { "200": { "description": "Frame queued or applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/studio/{studio}/scenes/{scene}/generate-animation": { "post": { "tags": [ "Public", "StudioScenes" ], "summary": "Generate or apply a scene animation", "description": "Requires a generated frame. Supplying video_url applies it immediately; supplying nothing queues it as pending for later generation.", "operationId": "generateStudioSceneAnimation", "parameters": [ { "name": "studio", "in": "path", "description": "Studio ID", "required": true, "schema": { "type": "string" } }, { "name": "scene", "in": "path", "description": "Scene ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioSceneGenerateAnimationRequest" } } } }, "responses": { "200": { "description": "Animation queued or applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioScenes" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "A generated frame is required before animating this scene" } } } }, "/api/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "Retrieve all user records for the authenticated user's active workspace", "operationId": "listUsers", "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Users" } } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "No active workspace set" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create user", "description": "Create a new user record and add to workspace", "operationId": "createUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStoreRequest" } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "401": { "description": "Unauthenticated or user does not belong to workspace" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Show user", "description": "Retrieve a specific user by ID", "operationId": "getUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - User is not in any of your workspaces" }, "404": { "description": "User not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Users" ], "summary": "Update user", "description": "Update an existing user record", "operationId": "updateUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID (sqid)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateRequest" } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Only the user or an owner or admin of a shared workspace can update this user" }, "404": { "description": "User not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete user", "description": "Delete a specific user", "operationId": "deleteUser", "parameters": [ { "name": "id", "in": "path", "description": "User ID (sqid)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "User deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - Only an owner or admin of a shared workspace can delete this user" }, "404": { "description": "User not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/webhook-events": { "get": { "tags": [ "Public", "WebhookEvents" ], "summary": "List webhook events", "description": "Retrieve all webhook event records", "operationId": "listWebhookEvents", "parameters": [ { "name": "status", "in": "query", "description": "Filter by event status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of webhook events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvents" } } } } }, "422": { "description": "No active workspace set" } } }, "post": { "tags": [ "Public", "WebhookEvents" ], "summary": "Create webhook event", "description": "Create a new webhook event record", "operationId": "createWebhookEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "responses": { "201": { "description": "Webhook event created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "422": { "description": "Validation error" } } } }, "/api/webhook-events/{id}": { "get": { "tags": [ "Public", "WebhookEvents" ], "summary": "Show webhook event", "description": "Retrieve a specific webhook event by id", "operationId": "getWebhookEvent", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Event ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "WebhookEvents" ], "summary": "Update webhook event", "description": "Update an existing webhook event record", "operationId": "updateWebhookEvent", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Event ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "responses": { "200": { "description": "Webhook event updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "WebhookEvents" ], "summary": "Delete webhook event", "description": "Delete a specific webhook event", "operationId": "deleteWebhookEvent", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Event ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook event deleted" }, "404": { "description": "Not found" } } } }, "/api/webhook-logs": { "get": { "tags": [ "WebhookLogs" ], "summary": "List webhook logs", "description": "Retrieve all webhook log records", "operationId": "listWebhookLogs", "parameters": [ { "name": "direction", "in": "query", "description": "Filter by direction (inbound/outbound)", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } } ], "responses": { "200": { "description": "List of webhook logs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookLogs" } } } } }, "422": { "description": "No active workspace set" } } }, "post": { "tags": [ "WebhookLogs" ], "summary": "Create webhook log", "description": "Create a new webhook log entry", "operationId": "createWebhookLog", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogs" } } } }, "responses": { "201": { "description": "Webhook log created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogs" } } } }, "422": { "description": "Validation error" } } } }, "/api/webhook-logs/{id}": { "get": { "tags": [ "WebhookLogs" ], "summary": "Show webhook log", "description": "Retrieve a specific webhook log by id", "operationId": "getWebhookLog", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Log ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook log details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogs" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "WebhookLogs" ], "summary": "Update webhook log", "description": "Update an existing webhook log entry", "operationId": "updateWebhookLog", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Log ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogs" } } } }, "responses": { "200": { "description": "Webhook log updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookLogs" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "WebhookLogs" ], "summary": "Delete webhook log", "description": "Delete a specific webhook log", "operationId": "deleteWebhookLog", "parameters": [ { "name": "id", "in": "path", "description": "Webhook Log ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook log deleted" }, "404": { "description": "Not found" } } } }, "/api/whiteboards/{whiteboard}/comments": { "get": { "tags": [ "Public", "WhiteboardComments" ], "summary": "List comments for a whiteboard", "description": "Retrieve comments for a whiteboard. By default returns only whiteboard-level comments. Use include_posts=true to also include comments on all posts within the whiteboard. Use all_comments=true to get the whiteboard-level comments together with the campaign-level comments left on every preview version of the whiteboard; version comments carry the preview they were left on.", "operationId": "listWhiteboardComments", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "include_posts", "in": "query", "description": "Include comments from all posts within this whiteboard", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "all_comments", "in": "query", "description": "Return whiteboard-level comments plus the campaign-level comments of every preview version, including soft-deleted ones, with approver flags. Takes precedence over include_posts.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of comments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comments" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Public", "WhiteboardComments" ], "summary": "Create comment", "description": "Create a new comment (or reply) on a whiteboard", "operationId": "createWhiteboardComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardCommentStoreRequest" } } } }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboards/{whiteboard}/comments/{comment}": { "get": { "tags": [ "Public", "WhiteboardComments" ], "summary": "Show comment", "description": "Retrieve a specific whiteboard comment", "operationId": "getWhiteboardComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Public", "WhiteboardComments" ], "summary": "Update comment", "description": "Update an existing whiteboard comment (users can only edit their own comments)", "operationId": "updateWhiteboardComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardCommentUpdateRequest" } } } }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Public", "WhiteboardComments" ], "summary": "Delete comment", "description": "Soft delete a whiteboard comment (users can only delete their own comments). Returns the deleted comment with is_deleted flag set to true.", "operationId": "deleteWhiteboardComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboards": { "get": { "tags": [ "Public", "Whiteboards" ], "summary": "List whiteboards", "description": "Retrieve all whiteboard records", "operationId": "listWhiteboards", "parameters": [ { "name": "campaign_id", "in": "query", "description": "Filter by campaign ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of whiteboards", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Whiteboards" } } } } }, "422": { "description": "No active workspace set" } } }, "post": { "tags": [ "Public", "Whiteboards" ], "summary": "Create whiteboard", "description": "Create a new whiteboard record", "operationId": "createWhiteboard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "workspace_id", "title" ], "properties": { "campaign_id": { "type": "string", "example": "cmpn_abc123", "nullable": true }, "workspace_id": { "type": "string", "example": "wrk_xyz789" }, "title": { "type": "string", "example": "Q1 Social Media Calendar", "maxLength": 255 }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01", "nullable": true }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31", "nullable": true }, "team": { "type": "string", "example": "Marketing Team", "nullable": true, "maxLength": 255 }, "shared": { "type": "array", "items": { "type": "string" }, "example": [ "usr_123", "usr_456" ], "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Whiteboard created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Whiteboards" } } } }, "422": { "description": "Validation error" } } } }, "/api/whiteboards/{id}": { "get": { "tags": [ "Public", "Whiteboards" ], "summary": "Show whiteboard", "description": "Retrieve a specific whiteboard by id", "operationId": "getWhiteboard", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard details with posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardsWithPosts" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "Whiteboards" ], "summary": "Update whiteboard", "description": "Update an existing whiteboard record", "operationId": "updateWhiteboard", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "campaign_id": { "type": "string", "example": "cmpn_abc123", "nullable": true }, "workspace_id": { "type": "string", "example": "wrk_xyz789" }, "title": { "type": "string", "example": "Q1 Social Media Calendar", "maxLength": 255 }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01", "nullable": true }, "end_date": { "type": "string", "format": "date", "example": "2025-03-31", "nullable": true }, "team": { "type": "string", "example": "Marketing Team", "nullable": true, "maxLength": 255 }, "shared": { "type": "array", "items": { "type": "string" }, "example": [ "usr_123", "usr_456" ], "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Whiteboard updated with posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardsWithPosts" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "Whiteboards" ], "summary": "Delete whiteboard", "description": "Delete a specific whiteboard", "operationId": "deleteWhiteboard", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Whiteboard deleted" }, "404": { "description": "Not found" } } } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}/comments": { "get": { "tags": [ "Public", "WhiteboardPostComments" ], "summary": "List comments for a whiteboard post", "description": "Retrieve all comments (including replies) for a specific whiteboard post", "operationId": "listWhiteboardPostComments", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of comments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Comments" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "post": { "tags": [ "Public", "WhiteboardPostComments" ], "summary": "Create comment", "description": "Create a new comment (or reply) on a whiteboard post", "operationId": "createWhiteboardPostComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "content" ], "properties": { "content": { "type": "string", "example": "This is a great post!" }, "parent_id": { "description": "Parent comment ID for replies", "type": "string", "example": "cmt_abc123", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}/comments/{comment}": { "get": { "tags": [ "Public", "WhiteboardPostComments" ], "summary": "Show comment", "description": "Retrieve a specific comment", "operationId": "getWhiteboardPostComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "WhiteboardPostComments" ], "summary": "Update comment", "description": "Update an existing comment (users can only edit their own comments)", "operationId": "updateWhiteboardPostComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "content": { "type": "string", "example": "Updated comment text" }, "is_resolved": { "type": "boolean", "example": true }, "resolved_by": { "type": "string", "example": "usr_xyz789" }, "resolved_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "responses": { "200": { "description": "Comment updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "WhiteboardPostComments" ], "summary": "Delete comment", "description": "Soft delete a comment (users can only delete their own comments). Returns the deleted comment with is_deleted flag set to true.", "operationId": "deleteWhiteboardPostComment", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } }, { "name": "comment", "in": "path", "description": "Comment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comment deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/whiteboards/{whiteboard}/posts": { "get": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "List posts for a whiteboard", "description": "Retrieve all posts for a specific whiteboard", "operationId": "listWhiteboardPosts", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of whiteboard posts with pending AI post generations (URL crawl and repurpose)", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPosts" } }, "pending_generations": { "description": "In-flight and recently failed AI post generations (URL crawl and repurpose) for the whiteboard", "type": "array", "items": { "$ref": "#/components/schemas/PostGeneration" } } }, "type": "object" } } } }, "403": { "description": "Forbidden" } } }, "post": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Create whiteboard post", "description": "Create a new post for a whiteboard", "operationId": "createWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "channel_id" ], "properties": { "channel_id": { "type": "string", "example": "chn_abc123" }, "type": { "oneOf": [ { "$ref": "#/components/schemas/PostType" } ], "nullable": true }, "content": { "type": "string", "example": "Check out our new product!", "nullable": true }, "title": { "type": "string", "example": "Product Launch Post", "nullable": true, "maxLength": 255 }, "image_url": { "type": "string", "format": "url", "example": "https://example.com/image.jpg", "nullable": true }, "post_date": { "type": "string", "format": "date", "example": "2025-06-15", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" }, "example": [ "marketing", "product" ], "nullable": true }, "notes": { "type": "string", "example": "Internal notes", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "promo", "launch" ], "nullable": true }, "platform_metadata": { "type": "object", "example": { "boost": true }, "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/PostStatus" } ], "nullable": true }, "platform_ad_id": { "type": "string", "example": "ad_123456", "nullable": true }, "ad_status": { "type": "string", "example": "active", "nullable": true }, "ad_budget": { "type": "number", "format": "float", "example": 500, "nullable": true, "minimum": 0 }, "ad_objective": { "type": "string", "example": "conversions", "nullable": true }, "ad_targeting": { "type": "object", "example": { "age": "25-45", "location": "US" }, "nullable": true }, "order": { "type": "integer", "example": 0, "nullable": true, "minimum": 0 } }, "type": "object" } } } }, "responses": { "201": { "description": "Whiteboard post created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPosts" } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}": { "get": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Show whiteboard post", "description": "Retrieve a specific whiteboard post", "operationId": "getWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard post details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPosts" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Update whiteboard post", "description": "Update an existing whiteboard post", "operationId": "updateWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "channel_id": { "type": "string", "example": "chn_abc123" }, "type": { "oneOf": [ { "$ref": "#/components/schemas/PostType" } ], "nullable": true }, "content": { "type": "string", "example": "Check out our new product!", "nullable": true }, "title": { "type": "string", "example": "Product Launch Post", "nullable": true, "maxLength": 255 }, "image_url": { "type": "string", "format": "url", "example": "https://example.com/image.jpg", "nullable": true }, "post_date": { "type": "string", "format": "date", "example": "2025-06-15", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" }, "example": [ "marketing", "product" ], "nullable": true }, "notes": { "type": "string", "example": "Internal notes", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "promo", "launch" ], "nullable": true }, "platform_metadata": { "type": "object", "example": { "boost": true }, "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/PostStatus" } ], "nullable": true }, "platform_ad_id": { "type": "string", "example": "ad_123456", "nullable": true }, "ad_status": { "type": "string", "example": "active", "nullable": true }, "ad_budget": { "type": "number", "format": "float", "example": 500, "nullable": true, "minimum": 0 }, "ad_objective": { "type": "string", "example": "conversions", "nullable": true }, "ad_targeting": { "type": "object", "example": { "age": "25-45", "location": "US" }, "nullable": true }, "order": { "type": "integer", "example": 0, "nullable": true, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Whiteboard post updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPosts" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Delete whiteboard post", "description": "Delete a specific whiteboard post", "operationId": "deleteWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Whiteboard post deleted" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/whiteboards/{whiteboard}/posts/reorder": { "post": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Reorder whiteboard posts", "description": "Batch update the order of posts for a whiteboard", "operationId": "reorderWhiteboardPosts", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "posts" ], "properties": { "posts": { "type": "array", "items": { "required": [ "id", "order" ], "properties": { "id": { "type": "string", "example": "wbp_abc123" }, "order": { "type": "integer", "example": 0 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Posts reordered successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPosts" } } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/whiteboards/{whiteboard}/posts/{whiteboard_post}/duplicate": { "post": { "tags": [ "Public", "WhiteboardPosts" ], "summary": "Duplicate a whiteboard post", "description": "Create a duplicate of an existing whiteboard post with DRAFT status, placed immediately after the original", "operationId": "duplicateWhiteboardPost", "parameters": [ { "name": "whiteboard", "in": "path", "description": "Whiteboard ID", "required": true, "schema": { "type": "string" } }, { "name": "whiteboard_post", "in": "path", "description": "Whiteboard Post ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard post duplicated, full updated posts list returned", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPosts" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/api/whiteboard-previews": { "get": { "tags": [ "Public", "WhiteboardPreviews" ], "summary": "List whiteboard previews", "description": "Retrieve all whiteboard preview records", "operationId": "listWhiteboardPreviews", "parameters": [ { "name": "whiteboard_id", "in": "query", "description": "Filter by whiteboard ID", "required": false, "schema": { "type": "string" } }, { "name": "latest", "in": "query", "description": "Filter for latest versions only", "required": false, "schema": { "type": "boolean" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "$ref": "#/components/schemas/WhiteboardPreviewStatus" } } ], "responses": { "200": { "description": "List of whiteboard previews", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPreviewListItems" } } } } }, "422": { "description": "No active workspace set" } } }, "post": { "tags": [ "Public", "WhiteboardPreviews" ], "summary": "Create whiteboard preview", "description": "Create a new whiteboard preview record and copy all posts from the source whiteboard", "operationId": "createWhiteboardPreview", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "whiteboard_id", "title" ], "properties": { "whiteboard_id": { "type": "string", "example": "sqid123" }, "campaign_id": { "type": "string", "example": "sqid789", "nullable": true }, "title": { "type": "string", "example": "Weekly Team Sync" }, "start_date": { "type": "string", "format": "date", "example": "2025-11-01", "nullable": true }, "end_date": { "type": "string", "format": "date", "example": "2025-11-30", "nullable": true }, "feedback": { "type": "string", "example": "Looks good!", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Whiteboard preview created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviews" } } } }, "422": { "description": "Validation error" } } } }, "/api/whiteboard-previews/{whiteboard_preview}/versions": { "get": { "tags": [ "WhiteboardPreviews" ], "summary": "List whiteboard preview versions", "description": "List same-whiteboard preview versions available from the current preview access context. Internal users use bearer auth; external users use ADSPR-EXTERNAL-TOKEN and receive respondable metadata only for the exact approval request tied to the token.", "operationId": "listWhiteboardPreviewVersions", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of whiteboard preview versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPreviewVersion" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Whiteboard preview not found" } }, "security": [ { "PreviewAccess": [] } ] } }, "/api/whiteboard-previews/{whiteboard_preview}/reapply": { "post": { "tags": [ "WhiteboardPreviews" ], "summary": "Reapply a whiteboard preview", "description": "Reapply the selected preview's post content to its active whiteboard. Referenced posts are updated in place, posts whose original active post was deleted are restored with new IDs, and active posts absent from the preview and their comments are permanently deleted. Preview versions and preview comments remain unchanged.", "operationId": "reapplyWhiteboardPreview", "parameters": [ { "name": "whiteboard_preview", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard preview reapplied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardsWithPosts" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Whiteboard preview not found" }, "422": { "description": "Preview cannot be reapplied because its post references, restoration channels, or campaign context are invalid" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboard-previews/{id}/discard": { "post": { "tags": [ "WhiteboardPreviews" ], "summary": "Discard whiteboard preview", "description": "Set a single whiteboard preview to discarded status.", "operationId": "discardWhiteboardPreview", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whiteboard preview discarded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteboardPreviews" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden - User not authorized to access this whiteboard preview" }, "404": { "description": "Whiteboard preview not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/whiteboard-previews/{id}/discard-previous": { "post": { "tags": [ "Public", "WhiteboardPreviews" ], "summary": "Discard all previous versions", "description": "Set all previous versions of this whiteboard preview to 'discarded' status, regardless of their current status (pending, approved, or rejected).", "operationId": "discardPreviousWhiteboardPreviews", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All previous versions discarded successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Previous versions discarded successfully" } }, "type": "object" } } } }, "403": { "description": "Forbidden - User not authorized to access this whiteboard preview" }, "404": { "description": "Whiteboard preview not found" }, "422": { "description": "No active workspace set" } } } }, "/api/whiteboard-previews/{id}": { "delete": { "tags": [ "Public", "WhiteboardPreviews" ], "summary": "Delete whiteboard preview", "description": "Delete a specific whiteboard preview and all its posts", "operationId": "deleteWhiteboardPreview", "parameters": [ { "name": "id", "in": "path", "description": "Whiteboard Preview ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Whiteboard preview deleted" }, "403": { "description": "Forbidden - User not authorized" }, "404": { "description": "Not found" } } } }, "/api/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "Retrieve all workspaces the authenticated user belongs to", "operationId": "listWorkspaces", "responses": { "200": { "description": "List of workspaces", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workspaces" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Workspaces" ], "summary": "Create workspace", "description": "Create a new workspace record", "operationId": "createWorkspace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceStoreRequest" } } } }, "responses": { "201": { "description": "Workspace created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspaces" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/workspaces/{id}": { "get": { "tags": [ "Workspaces" ], "summary": "Show workspace", "description": "Retrieve a specific workspace by id with billing information", "operationId": "getWorkspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace details with billing info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetail" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not a member of this workspace" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Workspaces" ], "summary": "Update workspace", "description": "Update an existing workspace record", "operationId": "updateWorkspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdateRequest" } } } }, "responses": { "200": { "description": "Workspace updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspaces" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" }, "404": { "description": "Not found" }, "422": { "description": "Validation error" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete workspace", "description": "Delete a specific workspace", "operationId": "deleteWorkspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Workspace deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not the workspace owner" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/workspaces/{id}/onboarding/complete": { "post": { "tags": [ "Workspaces" ], "summary": "Complete workspace onboarding", "description": "Marks the onboarding wizard as completed for the workspace, used for both finishing and skipping the wizard. Any workspace member may call it and the operation is idempotent: repeated calls keep the original completion timestamp.", "operationId": "completeWorkspaceOnboarding", "parameters": [ { "name": "id", "in": "path", "description": "Workspace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace details with onboarding completion timestamp", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDetail" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "User is not a member of this workspace" }, "404": { "description": "Not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/invites": { "get": { "tags": [ "WorkspaceInvites" ], "summary": "List pending invitations", "description": "Returns all pending, non-expired invitations for the authenticated user's active workspace. Only admins can list invitations.", "operationId": "listPendingInvites", "responses": { "200": { "description": "List of pending invitations", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInvitation" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not authorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Only admins can view invitations" } }, "type": "object" } } } }, "422": { "description": "No active workspace", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "No active workspace" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/invites/send": { "post": { "tags": [ "WorkspaceInvites" ], "summary": "Send a workspace invitation", "description": "Sends an invitation email to join the authenticated user's active workspace. Only admins can send invitations.", "operationId": "sendWorkspaceInvite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInviteRequest" } } } }, "responses": { "201": { "description": "Invitation sent successfully", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/WorkspaceInvitation" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not authorized to send invitations", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Only admins can send invitations" } }, "type": "object" } } } }, "422": { "description": "Validation error or business rule violation", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User is already a member of this workspace" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/invites/{token}": { "get": { "tags": [ "WorkspaceInvites" ], "summary": "Validate an invitation token", "description": "Returns invitation details for the given token. Public endpoint, no authentication required.", "operationId": "validateWorkspaceInvite", "parameters": [ { "name": "token", "in": "path", "description": "The invitation token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Valid invitation", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation is valid" }, "data": { "properties": { "workspace_name": { "type": "string", "example": "Design Team Workspace" }, "email": { "type": "string", "example": "newuser@example.com" }, "user_exists": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Invalid or nonexistent token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation not found" } }, "type": "object" } } } }, "409": { "description": "Invitation already accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation has already been accepted" } }, "type": "object" } } } }, "410": { "description": "Invitation expired", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation has expired" } }, "type": "object" } } } } }, "security": [] } }, "/api/invites/accept": { "post": { "tags": [ "WorkspaceInvites" ], "summary": "Accept a workspace invitation", "description": "Accepts a pending invitation, linking the authenticated user to the workspace with the assigned role.", "operationId": "acceptWorkspaceInvite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteRequest" } } } }, "responses": { "200": { "description": "Invitation accepted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation accepted successfully" }, "data": { "properties": { "workspace_id": { "type": "string", "example": "abc123" }, "workspace_name": { "type": "string", "example": "Design Team Workspace" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Email does not match invitation", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email does not match invitation" } }, "type": "object" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation not found" } }, "type": "object" } } } }, "409": { "description": "Invitation already accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation has already been accepted" } }, "type": "object" } } } }, "410": { "description": "Invitation expired", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invitation has expired" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "ActivityEvent": { "type": "string", "enum": [ "post.created", "post.updated", "post.duplicated", "post.published", "post.publish_failed", "posts.generated", "approval_request.created", "approval_request.responded", "whiteboard_preview.reapplied" ] }, "ApprovalRequestAssigneeType": { "type": "string", "enum": [ "internal_user", "external_user", "external_invite" ] }, "ApprovalRequestCandidateType": { "type": "string", "enum": [ "internal_user", "external_user" ] }, "ApprovalRequestStatus": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "BrandCompetitorChannelType": { "description": "Platforms a competitor profile can be added for. Every value is also a PostPlatform.", "type": "string", "enum": [ "facebook", "instagram", "linkedin", "x", "tiktok" ] }, "BrandExtractionStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "BrandGraphGroup": { "type": "string", "enum": [ "company_info", "brand_identity", "offerings", "social_proof" ] }, "BrandPromptType": { "type": "string", "enum": [ "content", "workflow" ] }, "CampaignStatus": { "type": "string", "enum": [ "draft", "active", "inactive" ] }, "CommentableType": { "type": "string", "enum": [ "whiteboard", "whiteboard_post", "whiteboard_preview", "whiteboard_preview_post" ] }, "ConnectorInstallationStatus": { "type": "string", "enum": [ "active", "inactive", "pending", "failed", "expired" ] }, "ConnectorType": { "type": "string", "enum": [ "n8n", "make", "pabbly", "zapier" ] }, "DeploymentStatus": { "type": "string", "enum": [ "started", "success", "failed", "rolled_back" ] }, "IndustryGroup": { "description": "Industry group of a brand or system prompt. Null means General.", "type": "string", "enum": [ "fashion_beauty", "food_beverage", "health_wellness", "home_lifestyle", "retail_ecommerce", "technology", "media_marketing", "professional_services", "travel_hospitality", "industrial" ] }, "MediaGenerationFailureReason": { "type": "string", "enum": [ "content_rejected", "provider_error", "timed_out", "storage_failed", "unexpected_error" ] }, "MediaGenerationStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "MediaGenerationType": { "type": "string", "enum": [ "image", "video" ] }, "NotificationType": { "type": "string", "enum": [ "crawl_post_created", "repurpose_post_created", "preview_comment_created", "brand_extraction_completed", "brand_extraction_failed", "approval_request_approved", "approval_request_rejected" ] }, "PlanType": { "type": "string", "enum": [ "brand", "agency", "pro" ] }, "PostGenerationFailureReason": { "type": "string", "enum": [ "no_supported_channels", "no_posts_generated", "unusable_content", "unexpected_error" ] }, "PostGenerationStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "PostGenerationType": { "type": "string", "enum": [ "crawl", "repurpose" ] }, "PostPlatform": { "type": "string", "enum": [ "facebook", "linkedin", "blog", "google_ads", "google_business", "figma", "instagram", "x", "tiktok" ] }, "PostStatus": { "type": "string", "enum": [ "draft", "scheduled", "published", "error" ] }, "PostType": { "type": "string", "enum": [ "carousel", "reel", "short", "single_image", "video", "story", "article", "design" ] }, "StudioAssetType": { "type": "string", "enum": [ "character", "location", "object" ] }, "StudioSceneAnimationStatus": { "type": "string", "enum": [ "none", "pending", "generated", "failed" ] }, "StudioSceneFrameStatus": { "type": "string", "enum": [ "draft", "pending", "generated", "failed" ] }, "StudioSceneVersionKind": { "type": "string", "enum": [ "frame", "animation" ] }, "StudioStatus": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "UsageEventType": { "type": "string", "enum": [ "signup", "first_brand_created", "first_content_generated", "first_approval_sent", "team_member_invited", "upgrade_triggered" ] }, "UserRole": { "type": "string", "enum": [ "admin", "agency_user", "partner", "external_approver" ] }, "UserType": { "type": "string", "enum": [ "internal", "external" ] }, "WhiteboardPreviewStatus": { "type": "string", "enum": [ "pending", "approved", "rejected", "discarded" ] }, "WorkspaceInvitationStatus": { "type": "string", "enum": [ "pending", "accepted" ] }, "ApprovalRequestRespondRequest": { "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/ApprovalRequestStatus" }, "feedback": { "type": "string", "example": "Looks good.", "nullable": true } }, "type": "object" }, "WhiteboardPreviewApprovalRequestStoreRequest": { "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/ApprovalRequestAssigneeType" }, "user_id": { "type": "string", "example": "usr123", "nullable": true }, "external_user_id": { "type": "string", "example": "ext123", "nullable": true }, "name": { "type": "string", "example": "Jane Client", "nullable": true, "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "jane@example.com", "nullable": true, "maxLength": 255 }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "ResetPasswordRequest": { "required": [ "email", "token", "password", "password_confirmation" ], "properties": { "email": { "description": "The email address for the account being reset", "type": "string", "format": "email", "example": "user@example.com" }, "token": { "description": "The password reset token from the reset link", "type": "string", "example": "reset-token-string" }, "password": { "description": "The new password", "type": "string", "format": "password", "example": "newStrongPassword123", "minLength": 8 }, "password_confirmation": { "description": "Confirmation of the new password", "type": "string", "format": "password", "example": "newStrongPassword123", "minLength": 8 } }, "type": "object" }, "SendPasswordResetLinkRequest": { "required": [ "email" ], "properties": { "email": { "description": "The email address requesting a password reset link", "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" }, "SystemPromptStoreRequest": { "required": [ "title", "content" ], "properties": { "title": { "description": "The title of the system prompt", "type": "string", "example": "Daily special spotlight", "maxLength": 255 }, "content": { "description": "The instruction the AI follows when this prompt is used", "type": "string", "example": "Write a post that spotlights today's special..." }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group that sees this prompt, null for General (all brands)" } }, "type": "object" }, "SystemPromptUpdateRequest": { "properties": { "title": { "description": "The title of the system prompt", "type": "string", "example": "Daily special spotlight", "maxLength": 255 }, "content": { "description": "The instruction the AI follows when this prompt is used", "type": "string", "example": "Write a post that spotlights today's special..." }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group that sees this prompt, null for General (all brands)" } }, "type": "object" }, "SelectPlanRequest": { "required": [ "plan" ], "properties": { "plan": { "$ref": "#/components/schemas/PlanType" } }, "type": "object" }, "TopUpCheckoutRequest": { "required": [ "variant_id" ], "properties": { "variant_id": { "description": "Lemon Squeezy variant ID of the top-up pack, as listed by GET /api/billing/top-up-packs", "type": "string", "example": "2280896" } }, "type": "object" }, "BrandAssetUpdateRequest": { "properties": { "color_scheme": { "description": "Brand color scheme as key-value pairs of hex color values", "type": "object", "example": { "primary": "#FF5733", "secondary": "#33FF57" }, "nullable": true }, "typography": { "description": "Brand typography settings", "properties": { "heading": { "description": "Heading font family", "type": "string", "example": "Inter", "nullable": true, "maxLength": 100 }, "paragraph": { "description": "Paragraph font family", "type": "string", "example": "Roboto", "nullable": true, "maxLength": 100 } }, "type": "object", "nullable": true }, "media": { "description": "Brand media assets", "properties": { "logo_url": { "description": "Direct URL to the brand logo image", "type": "string", "example": "https://example.com/logo.svg", "nullable": true, "maxLength": 2048 } }, "type": "object", "nullable": true } }, "type": "object" }, "BrandFromWebsiteRequest": { "required": [ "url" ], "properties": { "url": { "description": "Company website URL to create the brand from. The https scheme is assumed when omitted.", "type": "string", "format": "uri", "example": "https://acme.com", "maxLength": 2048 } }, "type": "object" }, "BrandSettingsUpdateRequest": { "properties": { "voice_guidelines": { "description": "Description of the brand voice and personality", "type": "string", "example": "Confident and approachable, speaks like a knowledgeable friend.", "nullable": true }, "tone_rules": { "description": "Tone guidance for writing in the brand voice", "type": "string", "example": "Keep sentences short. Avoid jargon and superlatives.", "nullable": true }, "hard_constraints": { "description": "Things the brand must never say or claim. Mirrored read-only into the brand graph.", "type": "array", "items": { "type": "string", "maxLength": 500 }, "example": [ "Never mention competitors by name" ], "nullable": true, "maxItems": 50 }, "audience": { "description": "Description of the brand's target audience", "type": "string", "example": "Small business owners looking for affordable marketing automation.", "nullable": true } }, "type": "object" }, "BrandChannelUpdateRequest": { "required": [ "channels" ], "properties": { "channels": { "description": "List of brand channels with channel type and optional details", "type": "array", "items": { "required": [ "name", "channel_type" ], "properties": { "id": { "type": "string", "example": "chn_abc123", "nullable": true }, "name": { "type": "string", "example": "Main Facebook Page", "maxLength": 255 }, "channel_type": { "$ref": "#/components/schemas/PostPlatform" }, "details": { "type": "object", "example": { "url": "https://facebook.com/page" }, "nullable": true } }, "type": "object" } } }, "type": "object" }, "BrandCompetitorStoreRequest": { "required": [ "company_name", "channels" ], "properties": { "company_name": { "description": "Name of the competing company", "type": "string", "example": "Acme Coffee", "maxLength": 255 }, "website": { "description": "Website of the competitor", "type": "string", "example": "https://acme.example", "nullable": true, "maxLength": 255 }, "address": { "description": "Street address of the competitor", "type": "string", "example": "Slovenska cesta 1", "nullable": true, "maxLength": 255 }, "city": { "description": "City of the competitor", "type": "string", "example": "Ljubljana", "nullable": true, "maxLength": 100 }, "telephone": { "description": "Phone number of the competitor", "type": "string", "example": "+386 1 234 5678", "nullable": true, "maxLength": 30 }, "email": { "description": "Contact email of the competitor", "type": "string", "format": "email", "example": "hello@acme.example", "nullable": true, "maxLength": 255 }, "channels": { "description": "Social profiles of the competitor. At least one is required.", "type": "array", "items": { "$ref": "#/components/schemas/BrandCompetitorChannelInput" }, "minItems": 1 } }, "type": "object" }, "BrandCompetitorChannelInput": { "required": [ "name", "channel_type", "details" ], "properties": { "id": { "description": "ID of an existing channel to keep when updating a competitor. Omit it to add a new channel.", "type": "string", "example": "abc123", "nullable": true }, "name": { "description": "Display name of the profile", "type": "string", "example": "Acme Coffee", "maxLength": 255 }, "channel_type": { "$ref": "#/components/schemas/BrandCompetitorChannelType" }, "details": { "description": "Profile details", "required": [ "url" ], "properties": { "url": { "description": "Public http or https URL of the profile", "type": "string", "format": "uri", "example": "https://www.facebook.com/acmecoffee", "maxLength": 2048 } }, "type": "object" } }, "type": "object" }, "BrandCompetitorUpdateRequest": { "required": [ "company_name", "channels" ], "properties": { "company_name": { "description": "Name of the competing company", "type": "string", "example": "Acme Coffee", "maxLength": 255 }, "website": { "description": "Website of the competitor", "type": "string", "example": "https://acme.example", "nullable": true, "maxLength": 255 }, "address": { "description": "Street address of the competitor", "type": "string", "example": "Slovenska cesta 1", "nullable": true, "maxLength": 255 }, "city": { "description": "City of the competitor", "type": "string", "example": "Ljubljana", "nullable": true, "maxLength": 100 }, "telephone": { "description": "Phone number of the competitor", "type": "string", "example": "+386 1 234 5678", "nullable": true, "maxLength": 30 }, "email": { "description": "Contact email of the competitor", "type": "string", "format": "email", "example": "hello@acme.example", "nullable": true, "maxLength": 255 }, "channels": { "description": "Full list of the competitor's profiles. Channels sent with an id are updated, channels without one are added, and existing channels left out are deleted. At least one is required.", "type": "array", "items": { "$ref": "#/components/schemas/BrandCompetitorChannelInput" }, "minItems": 1 } }, "type": "object" }, "BrandExtractionStoreRequest": { "required": [ "url" ], "properties": { "url": { "description": "Company website URL to extract brand information from. The https scheme is assumed when omitted.", "type": "string", "format": "uri", "example": "https://acme.com", "maxLength": 2048 }, "force": { "description": "When true, skips the reuse of a recent completed extraction for the same URL and always runs a fresh extraction.", "type": "boolean", "example": false } }, "type": "object" }, "UpdateBrandGraphCompanyInfoRequest": { "description": "Editable company level facts of the brand graph", "properties": { "taglines": { "description": "Short brand taglines", "type": "array", "items": { "type": "string", "maxLength": 255 }, "example": [ "Wake Up To More" ], "nullable": true }, "value_prop": { "description": "Value proposition of the brand", "type": "string", "example": "Small batch coffee roasted the morning it ships.", "nullable": true }, "mission_vision": { "description": "Mission and vision statement", "type": "string", "example": "Make great coffee an everyday habit.", "nullable": true }, "key_people": { "description": "People associated with the brand", "type": "array", "items": { "required": [ "name", "role" ], "properties": { "name": { "type": "string", "example": "Jane Doe", "maxLength": 255 }, "role": { "type": "string", "example": "Founder", "maxLength": 255 } }, "type": "object" }, "nullable": true }, "brand_promises": { "description": "Promises the brand makes to its customers", "type": "array", "items": { "type": "string", "maxLength": 500 }, "example": [ "Roasted to order" ], "nullable": true } }, "type": "object" }, "UpdateBrandGraphBrandIdentityRequest": { "description": "Editable voice and tone of the brand graph. The visual_assets and hard_constraints fields are read only here (hard constraints are edited on the brand page) and are rejected when sent.", "properties": { "voice_guidelines": { "description": "How the brand speaks", "type": "string", "example": "Warm and unpretentious.", "nullable": true }, "tone_rules": { "description": "Tone rules applied to generated copy", "type": "string", "example": "Short sentences. No jargon.", "nullable": true }, "audience": { "description": "Primary audience of the brand", "type": "string", "example": "Home brewers who care about origin.", "nullable": true } }, "type": "object" }, "UpdateBrandGraphOfferingsRequest": { "description": "Offerings are synced from external sources and are read only. Every field is rejected when sent, so only an empty object is accepted.", "type": "object" }, "UpdateBrandGraphSocialProofRequest": { "description": "Social proof holds no editable fields today. The testimonials and case_studies fields are synced from external sources and are rejected when sent, so only an empty object is accepted.", "type": "object" }, "BrandPromptStoreRequest": { "required": [ "type", "title", "content" ], "properties": { "type": { "$ref": "#/components/schemas/BrandPromptType" }, "title": { "description": "The title of the prompt", "type": "string", "example": "Welcome Message", "maxLength": 255 }, "content": { "description": "The content/body of the prompt", "type": "string", "example": "Generate a welcoming message for new customers..." } }, "type": "object" }, "BrandPromptUpdateRequest": { "required": [ "type", "title", "content" ], "properties": { "type": { "$ref": "#/components/schemas/BrandPromptType" }, "title": { "description": "The title of the prompt", "type": "string", "example": "Updated Title", "maxLength": 255 }, "content": { "description": "The content/body of the prompt", "type": "string", "example": "Updated prompt content..." } }, "type": "object" }, "CampaignStoreRequest": { "required": [ "brand_id", "title" ], "properties": { "brand_id": { "description": "Brand ID (sqid)", "type": "string", "example": "brnd_abc123" }, "title": { "description": "Campaign title", "type": "string", "example": "Summer Campaign 2025", "maxLength": 255 }, "description": { "description": "Campaign description", "type": "string", "example": "Campaign description", "nullable": true }, "start_date": { "description": "Campaign start date", "type": "string", "format": "date", "example": "2025-06-01", "nullable": true }, "end_date": { "description": "Campaign end date", "type": "string", "format": "date", "example": "2025-08-31", "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/CampaignStatus" } ], "nullable": true, "description": "Campaign status" } }, "type": "object" }, "CampaignUpdateRequest": { "required": [ "brand_id", "title" ], "properties": { "brand_id": { "description": "Brand ID (sqid)", "type": "string", "example": "brnd_abc123" }, "title": { "description": "Campaign title", "type": "string", "example": "Summer Campaign 2025", "maxLength": 255 }, "description": { "description": "Campaign description", "type": "string", "example": "Campaign description", "nullable": true }, "start_date": { "description": "Campaign start date", "type": "string", "format": "date", "example": "2025-06-01", "nullable": true }, "end_date": { "description": "Campaign end date", "type": "string", "format": "date", "example": "2025-08-31", "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/CampaignStatus" } ], "nullable": true, "description": "Campaign status" } }, "type": "object" }, "ConnectorInstallationStoreRequest": { "required": [ "connector_id", "brand_id" ], "properties": { "connector_id": { "description": "Connector ID", "type": "string", "example": "sqid2" }, "brand_id": { "description": "Brand ID the connector is installed for", "type": "string", "example": "sqid3" } }, "type": "object" }, "ConnectorInstallationUpdateRequest": { "properties": { "is_active": { "description": "Active status", "type": "boolean", "example": true, "nullable": true }, "webhook_url": { "description": "Webhook URL", "type": "string", "example": "https://example.com/webhook", "nullable": true } }, "type": "object" }, "CrawlURLRequest": { "required": [ "url", "brand_id", "whiteboard_id" ], "properties": { "url": { "description": "URL to crawl and extract content from", "type": "string", "format": "uri", "example": "https://example.com/listing/123" }, "brand_id": { "description": "Sqid of the brand", "type": "string", "example": "brd123" }, "whiteboard_id": { "description": "Sqid of the whiteboard", "type": "string", "example": "wht123" } }, "type": "object" }, "StudioStoreRequest": { "required": [ "brand_id", "title" ], "properties": { "brand_id": { "type": "string", "example": "brnd_abc123" }, "title": { "type": "string", "example": "Product Launch Video", "maxLength": 255 }, "status": { "oneOf": [ { "$ref": "#/components/schemas/StudioStatus" } ], "nullable": true }, "settings": { "type": "object", "nullable": true } }, "type": "object" }, "StudioAssetStoreRequest": { "required": [ "type", "name" ], "properties": { "type": { "$ref": "#/components/schemas/StudioAssetType" }, "name": { "type": "string", "example": "Maya", "maxLength": 255 }, "reference_images": { "type": "array", "items": { "type": "string" }, "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true } }, "type": "object" }, "StudioSceneAttachAssetRequest": { "required": [ "studio_asset_id" ], "properties": { "studio_asset_id": { "type": "string", "example": "stas_abc123" }, "overrides": { "description": "Scene-specific changes (e.g. expression, clothing) applied without changing the shared asset", "type": "object", "nullable": true } }, "type": "object" }, "StudioSceneGenerateAnimationRequest": { "properties": { "video_url": { "description": "Directly supplied animation clip (stub for the generation pipeline)", "type": "string", "nullable": true } }, "type": "object" }, "StudioSceneGenerateFrameRequest": { "properties": { "prompt": { "description": "Idea/description prompt to queue frame generation", "type": "string", "nullable": true }, "image_url": { "description": "Directly supplied image (upload or replace action)", "type": "string", "nullable": true }, "reference_scene_id": { "description": "Use a previous scene's frame as a reference", "type": "string", "nullable": true } }, "type": "object" }, "StudioSceneStoreRequest": { "properties": { "title": { "type": "string", "nullable": true, "maxLength": 255 }, "prompt": { "type": "string", "example": "Maya holds @SerumBottle in @Bathroom.", "nullable": true }, "camera": { "type": "object", "example": { "angle": "eye-level", "movement": "slow push-in" }, "nullable": true }, "duration_seconds": { "type": "integer", "example": 5, "nullable": true }, "subject_action": { "type": "string", "example": "Maya lifts the bottle and smiles.", "nullable": true }, "end_frame_image_url": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "order": { "type": "integer", "nullable": true } }, "type": "object" }, "UserStoreRequest": { "required": [ "name", "email", "password", "active_workspace_id" ], "properties": { "name": { "description": "Full name of the user", "type": "string", "example": "Alice Example", "maxLength": 255 }, "email": { "description": "Unique email address", "type": "string", "format": "email", "example": "alice@example.com", "maxLength": 255 }, "password": { "description": "User password", "type": "string", "format": "password", "example": "strongPassword123" }, "active": { "description": "Whether the user is active", "type": "boolean", "example": true, "nullable": true }, "active_workspace_id": { "description": "Sqid of the workspace to assign", "type": "string", "example": "wks123" }, "user_type": { "description": "Role type of the user", "type": "string", "example": "user", "nullable": true, "enum": [ "user", "freelancer" ] } }, "type": "object" }, "UserUpdateRequest": { "properties": { "name": { "description": "Full name of the user", "type": "string", "example": "Alice Example", "maxLength": 255 }, "email": { "description": "Unique email address. Only the user themselves can change it.", "type": "string", "format": "email", "example": "alice@example.com", "maxLength": 255 }, "password": { "description": "New password. Only the user themselves can change it.", "type": "string", "format": "password", "example": "newStrongPassword123" }, "active": { "description": "Whether the user is active", "type": "boolean", "example": true, "nullable": true }, "active_workspace_id": { "description": "Sqid of the workspace to assign. Must be a workspace the user belongs to.", "type": "string", "example": "wks123", "nullable": true }, "user_type": { "description": "Role type of the user. Only a workspace owner or admin can change it, never on themselves.", "type": "string", "example": "user", "nullable": true, "enum": [ "user", "freelancer" ] } }, "type": "object" }, "WhiteboardCommentStoreRequest": { "required": [ "content" ], "properties": { "content": { "description": "Comment content", "type": "string", "example": "This is a comment on the whiteboard." }, "parent_id": { "description": "Parent comment ID (sqid) for replies", "type": "string", "example": "cmt_abc123", "nullable": true } }, "type": "object" }, "WhiteboardCommentUpdateRequest": { "properties": { "content": { "description": "Comment content", "type": "string", "example": "Updated comment text." }, "is_resolved": { "description": "Whether the comment is resolved", "type": "boolean", "example": true, "nullable": true }, "resolved_by": { "description": "User ID (sqid) who resolved the comment", "type": "string", "example": "usr_xyz789", "nullable": true }, "resolved_at": { "description": "Timestamp when the comment was resolved", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "WhiteboardPostGenerateFromPromptRequest": { "required": [ "brand_prompt_id", "content" ], "properties": { "brand_prompt_id": { "description": "Sqid of the selected brand content prompt", "type": "string", "example": "prm123", "minLength": 1 }, "content": { "description": "The actual content or user input to generate post content from", "type": "string", "example": "Announce our new spring campaign with 20% off selected services.", "minLength": 1 } }, "type": "object" }, "WhiteboardPostRepurposeRequest": { "required": [ "brand_prompt_id", "channel_id", "content" ], "properties": { "brand_prompt_id": { "description": "Sqid of the selected brand content prompt", "type": "string", "example": "prm_abc123", "minLength": 1 }, "channel_id": { "description": "Sqid of the brand channel the repurposed draft post is created on", "type": "string", "example": "chn_abc123", "minLength": 1 }, "content": { "description": "The source content that is repurposed for the target channel", "type": "string", "example": "Announce our new spring campaign with 20% off selected services.", "minLength": 1 } }, "type": "object" }, "WhiteboardPreviewCommentStoreRequest": { "required": [ "content" ], "properties": { "content": { "description": "Comment content", "type": "string", "example": "This is a comment on the preview." }, "parent_id": { "description": "Parent comment ID (sqid) for replies", "type": "string", "example": "cmt_abc123", "nullable": true } }, "type": "object" }, "WhiteboardPreviewCommentUpdateRequest": { "properties": { "content": { "description": "Comment content", "type": "string", "example": "Updated comment text." } }, "type": "object" }, "WorkspaceStoreRequest": { "required": [ "name" ], "properties": { "name": { "description": "Workspace name", "type": "string", "example": "Design Team Workspace", "maxLength": 255 }, "description": { "description": "Workspace description", "type": "string", "example": "Workspace for the design and creative teams.", "maxLength": 1000 } }, "type": "object" }, "WorkspaceUpdateRequest": { "properties": { "name": { "description": "Workspace name", "type": "string", "example": "Design Team Workspace", "maxLength": 255 }, "owner_id": { "description": "Owner user ID (sqid)", "type": "string", "example": "abc123" } }, "type": "object" }, "AcceptInviteRequest": { "required": [ "token" ], "properties": { "token": { "description": "The invitation token received via email", "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0..." } }, "type": "object" }, "SendInviteRequest": { "required": [ "email", "role" ], "properties": { "email": { "description": "The email address of the person to invite", "type": "string", "format": "email", "example": "newuser@example.com" }, "role": { "description": "The role to assign to the invited user", "type": "string", "example": "agency_user", "enum": [ "admin", "agency_user" ] } }, "type": "object" }, "AICreditUsage": { "properties": { "id": { "type": "string", "example": "abc123" }, "workspace_id": { "type": "string", "example": "wks123", "nullable": true }, "brand_id": { "type": "string", "example": "brd123", "nullable": true }, "used_by_user_id": { "type": "string", "example": "usr123", "nullable": true }, "usage_type": { "type": "string", "example": "text_generation" }, "credits_used": { "type": "integer", "example": 25 }, "reference_id": { "type": "string", "example": "ref123", "nullable": true }, "details": { "type": "object", "example": { "prompt": "Write a poem" }, "nullable": true }, "used_at": { "type": "string", "format": "date-time", "example": "2024-06-07T12:00:00Z", "nullable": true } }, "type": "object" }, "ActivityItem": { "required": [ "id", "event_id", "event_type", "status", "attempts", "payload", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "example": "evt_abc123" }, "event_id": { "description": "Delivery key, one per post and post date", "type": "string", "example": "whiteboard_post.published:pst_abc123:1760518800", "nullable": true }, "event_type": { "type": "string", "example": "whiteboard_post.published" }, "status": { "description": "pending, delivered, failed, or cancelled when the post was moved to another date", "type": "string", "example": "delivered", "nullable": true }, "attempts": { "type": "integer", "example": 1 }, "connector_installation_id": { "type": "string", "example": "cin_abc123", "nullable": true }, "connector": { "properties": { "id": { "type": "string", "example": "con_abc123" }, "name": { "type": "string", "example": "Connector name" }, "slug": { "type": "string", "example": "connector-name" }, "logo_url": { "type": "string", "example": "https://example.com/logo.png", "nullable": true } }, "type": "object", "nullable": true }, "payload": { "type": "object", "example": { "whiteboard_id": "wht_abc123", "whiteboard_post_id": "pst_abc123" }, "nullable": true }, "response": { "type": "object", "example": { "status_code": 200, "body": { "ok": true } }, "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ActivityLog": { "required": [ "id", "event", "description", "created_at" ], "properties": { "id": { "type": "string", "example": "act_abc123" }, "event": { "$ref": "#/components/schemas/ActivityEvent" }, "description": { "type": "string", "example": "Created post Product Launch" }, "causer": { "description": "The actor who performed the activity; null for system activities", "properties": { "id": { "type": "string", "example": "usr_abc123" }, "type": { "type": "string", "example": "user", "enum": [ "user", "external_user" ] }, "name": { "type": "string", "example": "Jane Doe", "nullable": true } }, "type": "object", "nullable": true }, "subject": { "description": "The entity the activity was performed on; null when it no longer exists", "properties": { "id": { "type": "string", "example": "pst_abc123" }, "type": { "type": "string", "example": "whiteboard_post" } }, "type": "object", "nullable": true }, "properties": { "type": "object", "example": { "whiteboard_id": "wht_abc123" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ApprovalRequestCandidate": { "properties": { "type": { "$ref": "#/components/schemas/ApprovalRequestCandidateType" }, "id": { "type": "string", "example": "usr123", "nullable": true }, "name": { "type": "string", "example": "Jane Doe", "nullable": true }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "already_assigned": { "type": "boolean", "example": false }, "approval_request_id": { "type": "string", "example": "apr123", "nullable": true } }, "type": "object" }, "ApprovalRequests": { "properties": { "id": { "type": "string", "example": "apr123" }, "workspace_id": { "type": "string", "example": "wsp123" }, "whiteboard_preview_id": { "type": "string", "example": "prv123", "nullable": true }, "whiteboard_id": { "type": "string", "example": "wbd123", "nullable": true }, "whiteboard_preview": { "properties": { "id": { "type": "string", "example": "prv123" }, "title": { "type": "string", "example": "Spring Campaign Preview", "nullable": true }, "version": { "type": "integer", "example": 1, "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/WhiteboardPreviewStatus" } ], "nullable": true } }, "type": "object", "nullable": true }, "campaign": { "properties": { "id": { "type": "string", "example": "cmp123" }, "title": { "type": "string", "example": "Spring Campaign", "nullable": true } }, "type": "object", "nullable": true }, "brand": { "properties": { "id": { "type": "string", "example": "brd123" }, "name": { "type": "string", "example": "Acme", "nullable": true }, "logo_url": { "description": "Brand logo URL from brand assets, when available", "type": "string", "example": "https://acme.com/logo.svg", "nullable": true } }, "type": "object", "nullable": true }, "requester_id": { "type": "string", "example": "usr123" }, "approver_type": { "$ref": "#/components/schemas/ApprovalRequestCandidateType" }, "approver_id": { "type": "string", "example": "usr456" }, "approver": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Users" }, { "$ref": "#/components/schemas/ExternalUsers" } ] }, "status": { "$ref": "#/components/schemas/ApprovalRequestStatus" }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "viewed_at": { "type": "string", "format": "date-time", "nullable": true }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "feedback": { "type": "string", "nullable": true }, "approval_url": { "description": "Link sent to the approver by email. Includes the access token for external approvers, so anyone holding it can respond.", "type": "string", "example": "https://app.adspire.ai/campaigns/wbd123/approval/prv123?token=abc123", "nullable": true } }, "type": "object" }, "BackofficeApproval": { "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ApprovalRequestStatus" }, "is_overdue": { "description": "Pending and past its due date", "type": "boolean" }, "workspace": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "campaign": { "type": "string", "nullable": true }, "preview": { "type": "string", "nullable": true }, "requester": { "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object", "nullable": true }, "approver": { "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "is_external": { "type": "boolean" } }, "type": "object", "nullable": true }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "viewed_at": { "type": "string", "format": "date-time", "nullable": true }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "BackofficeConnectorDefinition": { "properties": { "slug": { "type": "string", "example": "woocommerce" }, "name": { "type": "string" }, "base_url": { "type": "string", "format": "uri" }, "manifest_version": { "type": "string" }, "scope": { "type": "string", "enum": [ "brand", "workspace" ] }, "store_field": { "type": "string" }, "auth_type": { "type": "string" }, "install_fields": { "type": "array", "items": { "type": "object" }, "nullable": true }, "capabilities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "events": { "type": "array", "items": { "type": "string" }, "nullable": true }, "ui_actions": { "type": "array", "items": { "type": "object" }, "nullable": true }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "approved" ] }, "workspace": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "BackofficePublishingIssue": { "properties": { "id": { "type": "string" }, "title": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "error" }, "issue": { "type": "string", "enum": [ "error", "overdue" ] }, "post_date": { "type": "string", "format": "date-time", "nullable": true }, "channel": { "type": "string", "nullable": true }, "campaign": { "type": "string", "nullable": true }, "workspace": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "failed_events": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "attempts": { "type": "integer" }, "will_retry": { "type": "boolean" }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" }, "BackofficeUser": { "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "user_type": { "type": "string", "example": "user" }, "active": { "type": "boolean" }, "workspaces_count": { "type": "integer" }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "BackofficeWorkspaceDetail": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BackofficeWorkspace" }, { "properties": { "plan": { "properties": { "name": { "type": "string", "example": "pro" }, "is_cancelled": { "type": "boolean" }, "is_resumable": { "type": "boolean" }, "past_due": { "type": "boolean" }, "expires_within": { "type": "string", "example": "15.01.2027", "nullable": true } }, "type": "object" }, "onboarding_completed_at": { "type": "string", "format": "date-time", "nullable": true }, "members": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "brands": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string", "nullable": true }, "channels": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "connector_installations": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "connector": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "status": { "type": "string" }, "is_active": { "type": "boolean" }, "last_webhook_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "last_webhook_received_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "brand_connector_installations": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "brand": { "type": "string", "nullable": true }, "connector_type": { "type": "string" }, "status": { "type": "string" }, "installed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } }, "type": "object" } ] }, "BackofficeWorkspace": { "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Acme Workspace" }, "owner": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object", "nullable": true }, "users_count": { "type": "integer", "example": 3 }, "brands_count": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "format": "date-time" }, "last_activity_at": { "description": "Latest login, brand, campaign, approval or token usage. Only on the list endpoint.", "type": "string", "format": "date-time", "nullable": true }, "dormant": { "description": "No activity in the last 30 days. Only on the list endpoint.", "type": "boolean", "nullable": true } }, "type": "object" }, "BrandAsset": { "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "xyz789" }, "color_scheme": { "description": "Brand color scheme as key-value pairs", "type": "object", "example": { "primary": "#FF5733", "secondary": "#33FF57" }, "nullable": true }, "typography": { "description": "Brand typography settings", "type": "object", "example": { "heading": "Inter", "paragraph": "Roboto" }, "nullable": true }, "media": { "description": "Brand media assets", "type": "object", "nullable": true } }, "type": "object" }, "BrandChannel": { "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "xyz789" }, "name": { "type": "string", "example": "Main Facebook Page" }, "channel_type": { "$ref": "#/components/schemas/PostPlatform" }, "details": { "type": "object", "example": { "name": "brandname" }, "nullable": true } }, "type": "object" }, "BrandsCompact": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Acme Corp" }, "website": { "type": "string", "example": "https://acme.com", "nullable": true }, "email": { "type": "string", "example": "contact@acme.com", "nullable": true }, "telephone": { "type": "string", "example": "+1234567890", "nullable": true }, "logo_url": { "description": "Brand logo URL from brand assets, when available", "type": "string", "example": "https://acme.com/logo.svg", "nullable": true }, "brand_channels": { "type": "array", "items": { "$ref": "#/components/schemas/BrandChannel" }, "nullable": true } }, "type": "object" }, "BrandCompetitorChannel": { "required": [ "id", "name", "channel_type", "details" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Acme Coffee" }, "channel_type": { "$ref": "#/components/schemas/BrandCompetitorChannelType" }, "details": { "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://www.facebook.com/acmecoffee" } }, "type": "object" } }, "type": "object" }, "BrandCompetitor": { "required": [ "id", "brand_id", "company_name", "website", "address", "city", "telephone", "email", "channels", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "xyz789" }, "company_name": { "type": "string", "example": "Acme Coffee" }, "website": { "type": "string", "example": "https://acme.example", "nullable": true }, "address": { "type": "string", "example": "Slovenska cesta 1", "nullable": true }, "city": { "type": "string", "example": "Ljubljana", "nullable": true }, "telephone": { "type": "string", "example": "+386 1 234 5678", "nullable": true }, "email": { "type": "string", "example": "hello@acme.example", "nullable": true }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/BrandCompetitorChannel" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-30T10:00:00.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-30T10:00:00.000000Z" } }, "type": "object" }, "BrandExtractionCompany": { "description": "Company information extracted from the website", "properties": { "name": { "type": "string", "example": "Acme Corp", "nullable": true }, "description": { "type": "string", "example": "Acme makes widgets.", "nullable": true }, "address": { "type": "string", "example": "1 Main St", "nullable": true }, "city": { "type": "string", "example": "Springfield", "nullable": true }, "telephone": { "type": "string", "example": "+1 555 0100", "nullable": true }, "email": { "type": "string", "example": "contact@acme.com", "nullable": true }, "industry": { "type": "string", "example": "Manufacturing", "nullable": true }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group the AI picked for the company, null when none fits" }, "country": { "type": "string", "example": "US", "nullable": true }, "website": { "type": "string", "example": "https://acme.com", "nullable": true }, "socials": { "type": "array", "items": { "type": "string" }, "example": [ "https://x.com/acme" ], "nullable": true } }, "type": "object", "nullable": true }, "BrandExtractionAssets": { "description": "Brand assets extracted from the website, in the shape accepted by the brand asset update endpoint", "properties": { "color_scheme": { "properties": { "colors": { "description": "Ordered brand colors: primary, secondary, accent", "type": "array", "items": { "type": "string" }, "example": [ "#00559b", "#be008b", "#ff7700" ] }, "background": { "type": "string", "example": "#ffffff", "nullable": true }, "text": { "type": "string", "example": "#181b48", "nullable": true }, "site_scheme": { "type": "string", "example": "light" } }, "type": "object" }, "typography": { "properties": { "heading": { "type": "string", "example": "Bunch-Bold", "nullable": true }, "paragraph": { "type": "string", "example": "Gilroy-Medium", "nullable": true } }, "type": "object" }, "media": { "properties": { "logo_url": { "type": "string", "example": "https://acme.com/logo.svg", "nullable": true }, "logo_svg": { "type": "string", "nullable": true }, "cover_images": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object", "nullable": true }, "BrandExtractionSettings": { "description": "Brand voice fields extracted from the website, in the shape accepted by the brand settings update endpoint", "properties": { "voice_guidelines": { "type": "string", "example": "Confident and approachable, speaks like a knowledgeable friend.", "nullable": true }, "tone_rules": { "type": "string", "example": "Keep sentences short. Avoid jargon and superlatives.", "nullable": true }, "audience": { "type": "string", "example": "Small business owners looking for affordable marketing automation.", "nullable": true } }, "type": "object", "nullable": true }, "BrandExtractionExtras": { "description": "Additional brand profile details extracted from the website, forwarded to the brand graph", "properties": { "taglines": { "type": "array", "items": { "type": "string" }, "example": [ "Widgets for the world" ] }, "value_proposition": { "type": "string", "example": "Durable widgets delivered anywhere within 48 hours.", "nullable": true }, "mission_vision": { "type": "string", "example": "Make widgets accessible to everyone. Become the default choice for reliable widgets worldwide.", "nullable": true }, "brand_promises": { "type": "array", "items": { "type": "string" }, "example": [ "Lifetime warranty on every widget" ] }, "key_people": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Jane Doe" }, "role": { "type": "string", "example": "Founder", "nullable": true } }, "type": "object" } }, "sub_brands": { "type": "array", "items": { "type": "string" }, "example": [ "Acme Pro" ] } }, "type": "object", "nullable": true }, "BrandExtractionData": { "description": "Extraction result once completed", "properties": { "company": { "$ref": "#/components/schemas/BrandExtractionCompany" }, "settings": { "$ref": "#/components/schemas/BrandExtractionSettings" }, "extras": { "$ref": "#/components/schemas/BrandExtractionExtras" }, "assets": { "$ref": "#/components/schemas/BrandExtractionAssets" }, "confidence": { "description": "Per-field confidence scores between 0 and 1", "type": "object", "example": { "primary_color": 0.95, "heading_font": 0.9, "logo": 0.98 }, "nullable": true, "additionalProperties": { "type": "number" } }, "evidence": { "description": "Per-field list of observation sources backing the extracted value", "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "platform": { "type": "string", "example": "shopify", "nullable": true }, "source_url": { "type": "string", "example": "https://acme.com", "nullable": true } }, "type": "object", "nullable": true }, "BrandExtraction": { "properties": { "id": { "type": "string", "example": "bex123" }, "brand_id": { "description": "Brand the extraction results are applied to, set when the extraction was started via the create-brand-from-website endpoint", "type": "string", "example": "brd123", "nullable": true }, "url": { "type": "string", "example": "https://acme.com" }, "status": { "$ref": "#/components/schemas/BrandExtractionStatus" }, "extracted_data": { "$ref": "#/components/schemas/BrandExtractionData" }, "failure_reason": { "description": "Set when status is failed: blocked, render_failed, unusable_content, invalid_result or unexpected_error", "type": "string", "example": "blocked", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "BrandGraphKeyPerson": { "description": "A person associated with the brand", "properties": { "name": { "type": "string", "example": "Jane Doe", "nullable": true }, "role": { "type": "string", "example": "Founder", "nullable": true } }, "type": "object" }, "BrandGraphLogo": { "description": "A brand logo, either a remote URL or inline SVG markup", "properties": { "type": { "type": "string", "example": "url", "enum": [ "url", "svg" ] }, "value": { "type": "string", "example": "https://acme.com/logo.svg" } }, "type": "object" }, "BrandGraphCompanyInfo": { "description": "Company level facts about the brand", "properties": { "taglines": { "type": "array", "items": { "type": "string" }, "example": [ "Wake Up To More" ] }, "value_prop": { "type": "string", "example": "Small batch coffee roasted the morning it ships.", "nullable": true }, "mission_vision": { "type": "string", "example": "Make great coffee an everyday habit.", "nullable": true }, "key_people": { "type": "array", "items": { "$ref": "#/components/schemas/BrandGraphKeyPerson" } }, "brand_promises": { "type": "array", "items": { "type": "string" }, "example": [ "Roasted to order" ] } }, "type": "object" }, "BrandGraphVisualAssets": { "description": "Visual identity of the brand", "properties": { "colors": { "description": "Ordered brand colors: primary, secondary, accent", "type": "array", "items": { "type": "string" }, "example": [ "#00559b", "#be008b" ] }, "background": { "type": "string", "example": "#ffffff", "nullable": true }, "text": { "type": "string", "example": "#181b48", "nullable": true }, "typography": { "properties": { "heading": { "type": "string", "example": "Inter", "nullable": true }, "paragraph": { "type": "string", "example": "Roboto", "nullable": true } }, "type": "object" }, "logos": { "type": "array", "items": { "$ref": "#/components/schemas/BrandGraphLogo" } } }, "type": "object" }, "BrandGraphBrandIdentity": { "description": "Voice, tone and visual identity of the brand", "properties": { "voice_guidelines": { "type": "string", "example": "Warm and unpretentious.", "nullable": true }, "tone_rules": { "type": "string", "example": "Short sentences. No jargon.", "nullable": true }, "audience": { "type": "string", "example": "Home brewers who care about origin.", "nullable": true }, "hard_constraints": { "description": "Mirrored from brand settings, edit them on the brand page. Read-only here.", "type": "array", "items": { "type": "string" }, "example": [ "Never claim organic certification" ] }, "visual_assets": { "$ref": "#/components/schemas/BrandGraphVisualAssets" } }, "type": "object" }, "BrandGraphOfferings": { "description": "What the brand sells or delivers", "properties": { "product_catalog": { "type": "array", "items": { "type": "object" }, "example": [ { "name": "Morning Blend" } ] }, "service_offerings": { "type": "array", "items": { "type": "object" }, "example": [ { "name": "Office subscription" } ] }, "projects": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "BrandGraphSocialProof": { "description": "Testimonials and case studies backing the brand", "properties": { "testimonials": { "type": "array", "items": { "type": "object" }, "example": [ { "quote": "Best coffee I have had.", "author": "Sam" } ] }, "case_studies": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "BrandGraph": { "description": "The brand knowledge graph, grouped by area", "properties": { "company_info": { "$ref": "#/components/schemas/BrandGraphCompanyInfo" }, "brand_identity": { "$ref": "#/components/schemas/BrandGraphBrandIdentity" }, "offerings": { "$ref": "#/components/schemas/BrandGraphOfferings" }, "social_proof": { "$ref": "#/components/schemas/BrandGraphSocialProof" } }, "type": "object" }, "BrandPrompt": { "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "description": "Owning brand, null for system prompts", "type": "string", "example": "xyz789", "nullable": true }, "is_system": { "description": "True for read-only system prompts managed by Adspire", "type": "boolean", "example": false }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group of a system prompt, null for General system prompts and brand prompts" }, "type": { "$ref": "#/components/schemas/BrandPromptType" }, "title": { "type": "string", "example": "Welcome Message" }, "content": { "type": "string", "example": "Generate a welcoming message..." } }, "type": "object" }, "Brands": { "required": [ "email" ], "properties": { "id": { "type": "string", "example": "abc123" }, "workspace_id": { "type": "string", "example": "sqid1" }, "company": { "oneOf": [ { "$ref": "#/components/schemas/Companies" } ], "nullable": true }, "name": { "type": "string", "example": "Acme Corp" }, "email": { "type": "string", "example": "contact@acme.com" }, "website": { "type": "string", "example": "https://acme.com", "nullable": true }, "address": { "type": "string", "example": "123 Main St", "nullable": true }, "city": { "type": "string", "example": "New York", "nullable": true }, "telephone": { "type": "string", "example": "+1234567890", "nullable": true }, "notes": { "type": "string", "example": "Important client", "nullable": true }, "selected_industry": { "type": "string", "example": "Technology", "nullable": true }, "industry_group": { "oneOf": [ { "$ref": "#/components/schemas/IndustryGroup" } ], "nullable": true, "description": "Industry group used to pick system prompts, null means General" }, "selected_country": { "type": "string", "example": "US", "nullable": true }, "contact": { "type": "string", "example": "John Doe", "nullable": true }, "logo_url": { "description": "Brand logo URL from brand assets, when available", "type": "string", "example": "https://acme.com/logo.svg", "nullable": true }, "brand_channels": { "type": "array", "items": { "$ref": "#/components/schemas/BrandChannel" }, "nullable": true } }, "type": "object" }, "BrandSetting": { "properties": { "id": { "type": "string", "example": "bst123" }, "brand_id": { "type": "string", "example": "brd123" }, "voice_guidelines": { "type": "string", "example": "Confident and approachable, speaks like a knowledgeable friend.", "nullable": true }, "hard_constraints": { "description": "Things the brand must never say or claim. Mirrored read-only into the brand graph.", "type": "array", "items": { "type": "string" }, "example": [ "Never mention competitors by name" ] }, "tone_rules": { "type": "string", "example": "Keep sentences short. Avoid jargon and superlatives.", "nullable": true }, "audience": { "type": "string", "example": "Small business owners looking for affordable marketing automation.", "nullable": true }, "logo": { "description": "Temporary URL of the uploaded brand logo", "type": "string", "nullable": true } }, "type": "object" }, "BrandSignalDailySnapshot": { "properties": { "snapshot_date": { "description": "UTC day the snapshot belongs to", "type": "string", "format": "date", "example": "2026-09-20" }, "captured_at": { "description": "When the snapshot row was last captured", "type": "string", "format": "date-time", "example": "2026-09-20T12:00:00.000000Z" }, "snapshot": { "$ref": "#/components/schemas/BrandSignalSnapshotPayload" } }, "type": "object" }, "BrandSignalSnapshotPayload": { "properties": { "brand": { "description": "Latest signals received for the brand itself, at most 50 items, newest first", "properties": { "total": { "description": "Number of distinct brand signals up to the snapshot time", "type": "integer", "example": 12 }, "latest_received_at": { "type": "string", "format": "date-time", "example": "2026-09-20T09:00:00+00:00", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BrandSignalSnapshotItem" } } }, "type": "object" }, "competitors": { "description": "Latest signals detected for the brand competitors, at most 50 items, newest first", "properties": { "total": { "description": "Number of distinct competitor signals up to the snapshot time", "type": "integer", "example": 4 }, "latest_detected_at": { "type": "string", "format": "date-time", "example": "2026-09-20T08:00:00+00:00", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BrandCompetitorSignalSnapshotItem" } } }, "type": "object" }, "change_summary": { "$ref": "#/components/schemas/BrandSignalChangeSummary" }, "captured_at": { "description": "When the snapshot payload was built", "type": "string", "format": "date-time", "example": "2026-09-20T12:00:00+00:00" } }, "type": "object" }, "BrandSignalSnapshotItem": { "properties": { "source": { "type": "string", "example": "instagram" }, "external_id": { "type": "string", "example": "post-1" }, "type": { "type": "string", "example": "new_post" }, "status": { "type": "string", "example": "new" }, "received_at": { "type": "string", "format": "date-time", "example": "2026-09-20T09:00:00+00:00", "nullable": true }, "payload": { "description": "Free-form signal payload from the source. An empty payload is serialized as an empty JSON array [] because of the array cast, so clients must accept both an object and [].", "type": "object", "example": { "caption": "Hello" }, "nullable": true } }, "type": "object" }, "BrandCompetitorSignalSnapshotItem": { "properties": { "competitor_id": { "type": "integer", "example": 7, "nullable": true }, "competitor_name": { "type": "string", "example": "Rival Co", "nullable": true }, "source": { "type": "string", "example": "website", "nullable": true }, "external_id": { "type": "string", "example": "launch-1", "nullable": true }, "type": { "type": "string", "example": "product_launch", "nullable": true }, "title": { "type": "string", "example": "Launch", "nullable": true }, "summary": { "type": "string", "example": "Launch summary", "nullable": true }, "main_url": { "type": "string", "example": "https://example.com/launch", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "ad", "promotion" ], "nullable": true }, "quality_score": { "description": "Data quality score between 0 and 1", "type": "number", "example": 0.8, "nullable": true }, "detected_at": { "type": "string", "format": "date-time", "example": "2026-09-20T08:00:00+00:00", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "example": "2026-09-19T15:00:00+00:00", "nullable": true }, "payload": { "description": "Free-form signal payload from the source. An empty payload is serialized as an empty JSON array [] because of the array cast, so clients must accept both an object and [].", "type": "object", "example": { "k": "v" }, "nullable": true } }, "type": "object" }, "BrandSignalChangeSummary": { "description": "Changes compared to the previous daily snapshot. The first snapshot of a brand is a baseline with no changes.", "properties": { "has_changes": { "type": "boolean", "example": true }, "brand_new_count": { "type": "integer", "example": 2 }, "brand_removed_count": { "type": "integer", "example": 0 }, "competitor_new_count": { "type": "integer", "example": 1 }, "competitor_removed_count": { "type": "integer", "example": 0 }, "brand_new_keys": { "description": "SHA1 keys of new brand signals, capped at 20", "type": "array", "items": { "type": "string" } }, "brand_removed_keys": { "description": "SHA1 keys of removed brand signals, capped at 20", "type": "array", "items": { "type": "string" } }, "competitor_new_keys": { "description": "SHA1 keys of new competitor signals, capped at 20", "type": "array", "items": { "type": "string" } }, "competitor_removed_keys": { "description": "SHA1 keys of removed competitor signals, capped at 20", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "CampaignListItems": { "required": [ "id", "title", "workspace_id", "whiteboard_statuses" ], "properties": { "id": { "type": "string", "example": "abc123" }, "title": { "type": "string", "example": "Spring Sale" }, "workspace_id": { "description": "Sqid of the workspace the campaign belongs to", "type": "string", "example": "wrk_abc123" }, "brand_id": { "type": "string", "example": "brnd_abc123", "nullable": true }, "brand_name": { "type": "string", "example": "Acme Corp", "nullable": true }, "brand_logo_url": { "description": "Brand logo URL from brand assets, when available", "type": "string", "example": "https://acme.com/logo.svg", "nullable": true }, "whiteboard_id": { "description": "Sqid of the campaign's first whiteboard", "type": "string", "example": "wht_abc123", "nullable": true }, "start_date": { "type": "string", "format": "date", "example": "2024-05-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-06-01" }, "status": { "type": "string", "example": "active", "nullable": true }, "whiteboard_statuses": { "description": "Aggregated whiteboard preview counts for the campaign", "properties": { "approved_count": { "type": "integer", "example": 2 }, "pending_count": { "type": "integer", "example": 1 }, "rejected_count": { "description": "Count of rejected and discarded previews", "type": "integer", "example": 0 } }, "type": "object" }, "cover_photo": { "description": "Image URL from the first whiteboard post that has one", "type": "string", "format": "url", "example": "https://example.com/image.jpg", "nullable": true } }, "type": "object" }, "Campaigns": { "required": [ "id", "title", "workspace_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "title": { "type": "string", "example": "Spring Sale" }, "workspace_id": { "description": "Sqid of the workspace the campaign belongs to", "type": "string", "example": "wrk_abc123" }, "brand": { "oneOf": [ { "$ref": "#/components/schemas/BrandsCompact" } ], "nullable": true }, "whiteboard_id": { "description": "Sqid of the campaign's first whiteboard", "type": "string", "example": "wht_abc123", "nullable": true }, "start_date": { "type": "string", "format": "date", "example": "2024-05-01" }, "end_date": { "type": "string", "format": "date", "example": "2024-06-01" }, "status": { "type": "string", "example": "active", "nullable": true }, "description": { "type": "string", "example": "Spring sale campaign targeting new customers", "nullable": true } }, "type": "object" }, "Comments": { "required": [ "content" ], "properties": { "id": { "type": "string", "example": "cmt_abc123" }, "commenter": { "oneOf": [ { "$ref": "#/components/schemas/Users" }, { "$ref": "#/components/schemas/ExternalUsers" } ] }, "commenter_source": { "$ref": "#/components/schemas/UserType" }, "commentable_type": { "$ref": "#/components/schemas/CommentableType" }, "commentable_id": { "description": "ID of the parent resource", "type": "string", "example": "pst_abc123", "nullable": true }, "parent_id": { "description": "Parent comment ID for replies", "type": "string", "example": "cmt_xyz789", "nullable": true }, "preview": { "description": "Preview version the comment was left on. Present for comments on a whiteboard preview, and for comments on a whiteboard preview post when the endpoint loads the post's preview.", "properties": { "id": { "type": "string", "example": "prv_abc123" }, "version": { "type": "integer", "example": 3 } }, "type": "object" }, "is_outdated": { "description": "Present on preview comment lists that span versions. True when the comment was left on a different preview version than the one requested.", "type": "boolean", "example": false }, "content": { "type": "string", "example": "This is a comment." }, "is_edited": { "description": "Indicates if comment was edited", "type": "boolean", "example": false }, "is_deleted": { "description": "Indicates if comment was soft deleted", "type": "boolean", "example": false }, "is_resolved": { "description": "Indicates if comment was resolved", "type": "boolean", "example": false }, "is_approver": { "description": "Indicates if comment author is assigned as an approver for the current preview", "type": "boolean", "example": false }, "replies_count": { "description": "Number of replies to this comment", "type": "integer", "example": 3 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ConnectorInstallation": { "properties": { "id": { "type": "string", "example": "abc123" }, "connector": { "properties": { "id": { "type": "string", "example": "sqid2" }, "name": { "type": "string", "example": "n8n" }, "type": { "$ref": "#/components/schemas/ConnectorType" }, "slug": { "type": "string", "example": "n8n" }, "logo_url": { "type": "string", "example": "https://example.com/logo.png", "nullable": true } }, "type": "object" }, "kind": { "type": "string", "enum": [ "webhook", "marketplace" ] }, "status": { "$ref": "#/components/schemas/ConnectorInstallationStatus" }, "is_active": { "type": "boolean", "example": true }, "brand_id": { "type": "string", "example": "sqid3", "nullable": true }, "webhook_url": { "type": "string", "example": "https://example.com/webhook", "nullable": true } }, "type": "object" }, "Connector": { "required": [ "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "n8n" }, "type": { "$ref": "#/components/schemas/ConnectorType" }, "slug": { "type": "string", "example": "n8n", "nullable": true }, "description": { "type": "string", "example": "Connect with n8n to automate workflows via webhooks.", "nullable": true }, "logo_url": { "type": "string", "example": "https://example.com/logo.png", "nullable": true }, "is_verified": { "type": "boolean", "example": true }, "is_featured": { "type": "boolean", "example": false }, "price_cents": { "type": "integer", "example": 0, "nullable": true }, "pricing_model": { "type": "string", "example": "free", "nullable": true }, "is_installed": { "description": "Whether the connector is installed in the current workspace", "type": "boolean", "example": false } }, "type": "object" }, "DeploymentEvent": { "required": [ "id", "service", "repo", "environment", "commit", "deployed_at", "status" ], "properties": { "id": { "type": "integer", "example": 1 }, "service": { "type": "string", "example": "api" }, "repo": { "type": "string", "example": "my-org/api" }, "environment": { "type": "string", "example": "production" }, "commit": { "type": "string", "example": "abc123" }, "image_sha": { "type": "string", "example": "sha256:xyz", "nullable": true }, "version": { "type": "string", "example": "v1.2.4", "nullable": true }, "deployed_at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/DeploymentStatus" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ExternalUsers": { "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Jane Doe", "nullable": true }, "email": { "type": "string", "format": "email", "example": "externaluser@example.com" }, "workspace_id": { "type": "string", "example": "wsp123", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Notifications": { "required": [ "id", "type", "data", "read_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "db2329cb-304c-4c07-9ddc-e854b73a48c2" }, "type": { "type": "string", "example": "App\\\\Notifications\\\\WhiteboardPreviewCommentCreated" }, "data": { "properties": { "message": { "type": "string", "example": "Jane Client added a comment to your whiteboard preview." }, "type": { "$ref": "#/components/schemas/NotificationType" }, "data": { "properties": { "whiteboard_preview_id": { "description": "SQID of the whiteboard preview", "type": "string", "example": "wpv_abc123", "nullable": true }, "whiteboard_preview_post_id": { "description": "SQID of the whiteboard preview post for post-level comments", "type": "string", "example": "wpp_abc123", "nullable": true }, "whiteboard_post_id": { "description": "SQID of the whiteboard post for generated-post notifications", "type": "string", "example": "pst_abc123", "nullable": true }, "whiteboard_id": { "description": "SQID of the whiteboard", "type": "string", "example": "wht_abc123" }, "comment_id": { "description": "SQID of the comment", "type": "string", "example": "cmt_abc123", "nullable": true }, "brand_extraction_id": { "description": "SQID of the brand extraction for extraction notifications", "type": "string", "example": "bex_abc123", "nullable": true }, "brand_id": { "description": "SQID of the brand the extraction was applied to", "type": "string", "example": "brn_abc123", "nullable": true }, "approval_request_id": { "description": "SQID of the approval request for approval response notifications", "type": "string", "example": "app_abc123", "nullable": true }, "status": { "description": "Extraction status for extraction notifications or approval request status for approval response notifications", "type": "string", "example": "completed", "nullable": true }, "type": { "type": "string", "example": "linkedin", "nullable": true } }, "type": "object" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-05-05T20:19:46.214504Z" } }, "type": "object" }, "read_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-05T20:19:46.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-05-05T20:19:46.000000Z" } }, "type": "object" }, "PostGenerationChannel": { "properties": { "id": { "type": "string", "example": "chn_abc123" }, "platform": { "type": "string", "example": "facebook" } }, "type": "object" }, "PostGeneration": { "properties": { "id": { "type": "string", "example": "pgn123" }, "url": { "description": "Crawled URL, null for generations that are not started from a URL", "type": "string", "example": "https://example.com/listing/123", "nullable": true }, "type": { "$ref": "#/components/schemas/PostGenerationType" }, "source_post_id": { "description": "Sqid of the post being repurposed, null for crawl generations", "type": "string", "example": "wbp123", "nullable": true }, "status": { "$ref": "#/components/schemas/PostGenerationStatus" }, "expected_post_count": { "description": "Number of posts this generation will create, one per channel", "type": "integer", "example": 3 }, "channels": { "description": "Brand channels the posts will be generated for", "type": "array", "items": { "$ref": "#/components/schemas/PostGenerationChannel" } }, "failure_reason": { "oneOf": [ { "$ref": "#/components/schemas/PostGenerationFailureReason" } ], "nullable": true, "description": "Set when status is failed" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StudioListItems": { "required": [ "id", "title", "workspace_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "brnd_abc123" }, "brand_name": { "type": "string", "example": "Acme Corp", "nullable": true }, "workspace_id": { "type": "string", "example": "wrk_abc123" }, "title": { "type": "string", "example": "Product Launch Video" }, "status": { "$ref": "#/components/schemas/StudioStatus" }, "scenes_count": { "type": "integer", "example": 3 }, "cover_photo": { "description": "Frame image from the first scene that has one", "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "TopUpPack": { "properties": { "variant_id": { "description": "Lemon Squeezy variant ID to pass to POST /api/billing/top-up", "type": "string", "example": "2280896" }, "credits": { "description": "Credits added to the workspace, in the same unit as ai_credits on the workspace", "type": "integer", "example": 100000 } }, "type": "object" }, "Users": { "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Alice Example" }, "email": { "type": "string", "format": "email", "example": "alice@example.com" }, "active_workspace_id": { "type": "string", "example": "sqid123", "nullable": true }, "user_type": { "type": "string", "example": "user", "enum": [ "user", "freelancer" ] }, "workspace_role": { "description": "User role within the active workspace", "type": "string", "example": "admin", "nullable": true, "enum": [ "admin", "agency_user", "partner", "external_approver" ] }, "is_owner": { "description": "Whether the user is the owner of the active workspace", "type": "boolean", "example": true }, "onboarding_completed": { "description": "Whether onboarding has been completed for the user's active workspace", "type": "boolean", "example": false }, "is_adspire_admin": { "description": "Whether the user belongs to the Adspire admin workspace", "type": "boolean", "example": false } }, "type": "object" }, "WebhookEvents": { "required": [ "id", "event_type", "payload", "status", "attempts", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "example": "abc123" }, "connector_installation_id": { "type": "string", "example": "def456", "nullable": true }, "event_id": { "description": "Delivery key, one per post and post date", "type": "string", "example": "whiteboard_post.published:pst_abc123:1760518800", "nullable": true }, "event_type": { "type": "string", "example": "whiteboard_post.published" }, "payload": { "type": "object", "example": { "whiteboard_post_id": "post123" }, "nullable": true }, "status": { "description": "pending, delivered, failed, or cancelled when the post was moved to another date", "type": "string", "example": "delivered", "nullable": true }, "response": { "type": "object", "example": { "status_code": 200, "body": { "ok": true } }, "nullable": true }, "attempts": { "type": "integer", "example": 1 }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "next_retry_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WebhookLogs": { "required": [ "id", "direction", "event_type", "payload", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "example": "abc123" }, "connector_installation_id": { "type": "string", "example": "def456", "nullable": true }, "direction": { "type": "string", "example": "outgoing", "enum": [ "incoming", "outgoing" ] }, "event_type": { "type": "string", "example": "whiteboard_post.published" }, "payload": { "type": "object", "example": { "whiteboard_post_id": "post123" }, "nullable": true }, "status_code": { "type": "string", "example": "200", "nullable": true }, "response": { "type": "object", "example": { "status_code": 200, "body": { "ok": true } }, "nullable": true }, "ip_address": { "type": "string", "example": "127.0.0.1", "nullable": true }, "user_agent": { "type": "string", "example": "Mozilla/5.0", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WhiteboardPreviewListItems": { "required": [ "id", "whiteboard_id", "status" ], "properties": { "id": { "type": "string", "example": "abc123" }, "whiteboard_id": { "type": "string", "example": "wht_abc123" }, "campaign_id": { "type": "string", "example": "cmpg_abc123", "nullable": true }, "status": { "$ref": "#/components/schemas/WhiteboardPreviewStatus" }, "version": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WhiteboardPreviews": { "required": [ "title", "whiteboard_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "whiteboard_id": { "type": "string", "example": "sqid456" }, "status": { "$ref": "#/components/schemas/WhiteboardPreviewStatus" }, "version": { "type": "integer", "example": 1 }, "campaign": { "oneOf": [ { "$ref": "#/components/schemas/Campaigns" } ], "nullable": true }, "created_by": { "$ref": "#/components/schemas/Users" }, "reviewed_by": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Users" }, { "$ref": "#/components/schemas/ExternalUsers" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WhiteboardPreviewVersion": { "properties": { "id": { "type": "string", "example": "prv123" }, "whiteboard_id": { "type": "string", "example": "wbd123" }, "title": { "type": "string", "example": "Spring Campaign Preview" }, "version": { "type": "integer", "example": 2 }, "status": { "$ref": "#/components/schemas/WhiteboardPreviewStatus" }, "approval_request_id": { "type": "string", "example": "apr123", "nullable": true }, "is_current": { "type": "boolean", "example": false }, "is_respondable": { "type": "boolean", "example": false } }, "type": "object" }, "WhiteboardPreviewsWithPosts": { "required": [ "title" ], "properties": { "id": { "type": "string", "example": "abc123" }, "title": { "type": "string", "example": "Weekly Team Sync" }, "status": { "$ref": "#/components/schemas/WhiteboardPreviewStatus" }, "approval_request_id": { "type": "string", "example": "apr123", "nullable": true }, "feedback": { "type": "string", "nullable": true }, "campaign": { "oneOf": [ { "$ref": "#/components/schemas/Campaigns" } ], "nullable": true }, "created_by": { "$ref": "#/components/schemas/Users" }, "created_at": { "type": "string", "format": "date-time" }, "reviewed_by": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Users" }, { "$ref": "#/components/schemas/ExternalUsers" } ] }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPreviewPosts" } } }, "type": "object" }, "WorkspaceDetail": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Design Team Workspace" }, "plan_name": { "description": "Current plan: brand, agency, pro, or trial", "type": "string", "example": "pro" }, "is_plan_cancelled": { "description": "Whether the subscription is cancelled", "type": "boolean", "example": false }, "is_subscription_resumable": { "description": "Whether the subscription can be resumed (on grace period)", "type": "boolean", "example": false }, "past_due": { "description": "Whether the subscription payment is past due", "type": "boolean", "example": false }, "plan_expires_within": { "description": "Date when the plan expires or renews", "type": "string", "example": "15.01.2025", "nullable": true }, "onboarding_completed_at": { "description": "When the onboarding wizard was completed or skipped for this workspace", "type": "string", "format": "date-time", "example": "2026-09-07T10:15:00.000000Z", "nullable": true }, "ai_credits": { "description": "AI credit balance. Monthly plan credits reset on the subscription renewal day and are spent first; top-up credits never expire.", "properties": { "quota": { "description": "Monthly plan credits", "type": "integer", "example": 500000 }, "used": { "description": "Credits used in the current billing period, including any covered by top-ups, so it can exceed quota", "type": "integer", "example": 12345 }, "monthly_remaining": { "description": "Monthly plan credits left in the current billing period", "type": "integer", "example": 487655 }, "top_up_remaining": { "description": "Purchased top-up credits left", "type": "integer", "example": 100000 }, "remaining": { "description": "Total credits available: monthly_remaining plus top_up_remaining when top-ups are usable", "type": "integer", "example": 587655 }, "period_start": { "type": "string", "format": "date-time", "example": "2026-10-05T00:00:00+00:00" } }, "type": "object" } }, "type": "object" }, "WorkspaceInvitation": { "properties": { "id": { "description": "The invitation ID", "type": "string", "example": "abc123" }, "email": { "description": "The invited email address", "type": "string", "format": "email", "example": "newuser@example.com" }, "workspace": { "description": "The workspace name", "type": "string", "example": "Design Team Workspace" }, "role": { "description": "The assigned role", "type": "string", "example": "agency_user" }, "status": { "description": "The invitation status", "type": "string", "example": "pending" }, "invited_by": { "description": "Name of the user who sent the invitation", "type": "string", "example": "Alice Example" }, "expires_at": { "description": "When the invitation expires", "type": "string", "format": "date-time" }, "created_at": { "description": "When the invitation was created", "type": "string", "format": "date-time" } }, "type": "object" }, "Workspaces": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Design Team Workspace" } }, "type": "object" }, "ApiKeys": { "required": [ "key", "user_id", "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "user_id": { "type": "string", "example": "def456" }, "key": { "type": "string", "example": "abc123DEF456ghi789JKL" }, "name": { "type": "string", "example": "Production Key" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Companies": { "required": [ "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Company DOO" }, "address": { "type": "string", "example": "123 Main St", "nullable": true }, "email": { "type": "string", "example": "contact@company.com", "nullable": true }, "phone": { "type": "string", "example": "+1234567890", "nullable": true } }, "type": "object" }, "Company Users": { "required": [ "name" ], "properties": { "id": { "type": "string", "example": "abc123" }, "user_id": { "type": "integer", "example": "" }, "company_id": { "type": "string", "example": "sqid24" } }, "type": "object" }, "Packages": { "required": [ "name", "version", "monthly_ai_credits" ], "properties": { "id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "example": "Pro Plan" }, "version": { "type": "string", "example": "1.0.0" }, "monthly_ai_credits": { "type": "integer", "example": 1000 }, "description": { "type": "string", "example": "Monthly subscription tier." }, "price": { "type": "number", "format": "float", "example": 19.99 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Studios": { "required": [ "title", "brand_id", "workspace_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "brnd_abc123" }, "workspace_id": { "type": "string", "example": "wrk_abc123" }, "title": { "type": "string", "example": "Product Launch Video" }, "status": { "$ref": "#/components/schemas/StudioStatus" }, "settings": { "type": "object", "nullable": true }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/StudioScenes" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StudioAssets": { "required": [ "name", "type", "brand_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "brand_id": { "type": "string", "example": "brnd_abc123" }, "type": { "$ref": "#/components/schemas/StudioAssetType" }, "name": { "type": "string", "example": "Maya" }, "reference_images": { "type": "array", "items": { "type": "string" }, "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "description": "Type-specific fields: wardrobe/voice for characters, lighting/visual_style for locations, important appearance details for objects", "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StudioScenes": { "required": [ "studio_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "studio_id": { "type": "string", "example": "stdo_abc123" }, "order": { "type": "integer", "example": 0 }, "title": { "type": "string", "nullable": true }, "prompt": { "description": "Raw text including @mentions of referenced assets", "type": "string", "nullable": true }, "frame_image_url": { "type": "string", "nullable": true }, "frame_status": { "$ref": "#/components/schemas/StudioSceneFrameStatus" }, "animation_video_url": { "type": "string", "nullable": true }, "animation_status": { "$ref": "#/components/schemas/StudioSceneAnimationStatus" }, "end_frame_image_url": { "type": "string", "nullable": true }, "camera": { "description": "e.g. {angle, movement}", "type": "object", "nullable": true }, "duration_seconds": { "type": "integer", "nullable": true }, "subject_action": { "type": "string", "nullable": true }, "is_animation_stale": { "description": "True when the frame changed after the current animation was generated", "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "assets": { "type": "array", "items": { "properties": { "asset": { "$ref": "#/components/schemas/StudioAssets" }, "overrides": { "description": "Scene-specific changes applied without changing the shared asset", "type": "object", "nullable": true } }, "type": "object" } }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/StudioSceneVersions" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StudioSceneVersions": { "properties": { "id": { "type": "string", "example": "abc123" }, "kind": { "$ref": "#/components/schemas/StudioSceneVersionKind" }, "url": { "type": "string", "nullable": true }, "source_prompt": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Whiteboards": { "required": [ "title", "workspace_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "campaign_id": { "type": "string", "example": "sqid2", "nullable": true }, "workspace_id": { "type": "string", "example": "sqid3" }, "title": { "type": "string", "example": "Sprint Planning Board" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01", "nullable": true }, "end_date": { "type": "string", "format": "date", "example": "2025-12-31", "nullable": true }, "team": { "type": "string", "example": "Marketing Team", "nullable": true }, "shared": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WhiteboardsWithPosts": { "allOf": [ { "$ref": "#/components/schemas/Whiteboards" }, { "properties": { "campaign": { "$ref": "#/components/schemas/Campaigns" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/WhiteboardPosts" } }, "pending_generations": { "description": "In-flight and recently failed AI post generations (URL crawl and repurpose) for the whiteboard", "type": "array", "items": { "$ref": "#/components/schemas/PostGeneration" } } }, "type": "object" } ] }, "WhiteboardPosts": { "required": [ "whiteboard_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "whiteboard_id": { "type": "string", "example": "sqid1" }, "channel": { "$ref": "#/components/schemas/BrandChannel" }, "type": { "oneOf": [ { "$ref": "#/components/schemas/PostType" } ], "nullable": true, "example": "single_image" }, "content": { "type": "string", "example": "Check out our new product!", "nullable": true }, "title": { "type": "string", "example": "New Product Launch", "nullable": true }, "image_url": { "type": "string", "example": "https://example.com/image.jpg", "nullable": true }, "post_date": { "type": "string", "format": "date-time", "example": "2025-10-15T10:00:00Z", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" }, "nullable": true }, "notes": { "type": "string", "example": "Remember to tag the brand account", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "platform_metadata": { "type": "object", "nullable": true }, "status": { "oneOf": [ { "$ref": "#/components/schemas/PostStatus" } ], "nullable": true, "example": "draft" }, "platform_ad_id": { "type": "string", "example": "ad_123456", "nullable": true }, "ad_status": { "type": "string", "example": "active", "nullable": true }, "ad_budget": { "type": "number", "format": "float", "example": 1500, "nullable": true }, "ad_objective": { "type": "string", "example": "conversions", "nullable": true }, "n8n_trigger_url": { "type": "string", "example": "https://n8n.com/webhook/test", "nullable": true }, "ad_targeting": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "WhiteboardPreviewPosts": { "properties": { "id": { "type": "string", "example": "pst_abc123" }, "whiteboard_preview_id": { "type": "string", "example": "prev_xyz789" }, "whiteboard_post_id": { "description": "Original whiteboard post ID", "type": "string", "example": "pst_xyz789", "nullable": true }, "channel": { "$ref": "#/components/schemas/BrandChannel" }, "type": { "oneOf": [ { "$ref": "#/components/schemas/PostType" } ], "nullable": true, "example": "single_image" }, "content": { "type": "string", "example": "Post content here" }, "title": { "type": "string", "example": "Campaign Post Title", "nullable": true }, "image_url": { "type": "string", "example": "https://example.com/image.jpg", "nullable": true }, "post_date": { "type": "string", "format": "date-time", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" }, "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "platform_metadata": { "type": "object", "nullable": true }, "approval": { "type": "boolean", "example": false }, "audience": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" }, "Workspace User": { "required": [ "user_id", "workspace_id" ], "properties": { "id": { "type": "string", "example": "abc123" }, "user_id": { "type": "string", "example": "sqid24" }, "workspace_id": { "type": "string", "example": "sqid24" }, "role": { "description": "User role within this workspace", "type": "string", "example": "admin", "nullable": true, "enum": [ "admin", "agency_user", "partner", "external_approver" ] } }, "type": "object" } }, "securitySchemes": { "ExternalAccess": { "type": "apiKey", "description": "External token for whiteboard preview approval/rejection (external users only)", "name": "ADSPR-EXTERNAL-TOKEN", "in": "header" }, "PreviewAccess": { "type": "apiKey", "description": "Accepts both JWT Bearer tokens (internal users) and external tokens (ADSPR-EXTERNAL-TOKEN header) for whiteboard preview access", "name": "Authorization or ADSPR-EXTERNAL-TOKEN", "in": "header" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter token in format (Bearer )" } } }, "tags": [ { "name": "AICreditUsage", "description": "Endpoints for managing AI credit usage" }, { "name": "Activity", "description": "Endpoints for viewing activity" }, { "name": "WhiteboardPostAssistant", "description": "AI assistant endpoints for whiteboard posts" }, { "name": "ApiKeys", "description": "Endpoints for managing API keys" }, { "name": "ApprovalRequests", "description": "Endpoints for managing approval requests" }, { "name": "Auth", "description": "Authentication and password management endpoints" }, { "name": "BackofficeSystemPrompts", "description": "Adspire admin endpoints for managing read-only system content prompts shown to brands by industry group" }, { "name": "Billing", "description": "Endpoints for managing subscriptions and billing" }, { "name": "BrandAssets", "description": "Endpoints for managing brand assets (colors, typography, media)" }, { "name": "BrandChannels", "description": "Endpoints for managing brand channels" }, { "name": "BrandCompetitors", "description": "Endpoints for managing the competitors of a brand" }, { "name": "Brands", "description": "Endpoints for managing brands" }, { "name": "BrandExtractions", "description": "Extract company information and brand assets from a website URL" }, { "name": "BrandGraph", "description": "Endpoints for reading the brand knowledge graph" }, { "name": "BrandPrompts", "description": "Endpoints for managing brand prompts" }, { "name": "BrandSettings", "description": "Manage brand voice settings and logo" }, { "name": "BrandSignals", "description": "Read daily snapshots of brand and competitor signals" }, { "name": "Campaigns", "description": "API Endpoints for managing campaigns" }, { "name": "Companies", "description": "Endpoints for managing companies" }, { "name": "Connectors", "description": "Endpoints for managing connectors" }, { "name": "ConnectorInstallations", "description": "Endpoints for managing connector installations" }, { "name": "Connector Definitions", "description": "Marketplace connector definitions" }, { "name": "Crawl", "description": "URL crawling and AI content extraction" }, { "name": "Deployments", "description": "Deployment tracking endpoints called from CI" }, { "name": "External Auth", "description": "Authentication endpoints for external users" }, { "name": "WhiteboardPreviewComments", "description": "Endpoints for managing comments on whiteboard previews (both internal and external users)" }, { "name": "External Whiteboard Previews", "description": "Endpoints for external users to view and approve/reject whiteboard previews" }, { "name": "WhiteboardPreviewPostComments", "description": "Endpoints for managing comments on whiteboard preview posts (both internal and external users)" }, { "name": "ExternalUsers", "description": "Endpoints for managing external users" }, { "name": "Notifications", "description": "Endpoints for managing notifications" }, { "name": "Packages", "description": "Endpoints for managing packages" }, { "name": "PostGenerations", "description": "AI post generations (URL crawl and repurpose) shown as ghost posts on the whiteboard" }, { "name": "StudioAssets", "description": "Endpoints for managing reusable Studio Characters, Locations and Objects" }, { "name": "Studios", "description": "Endpoints for managing studios (scene-based video workspaces)" }, { "name": "StudioScenes", "description": "Endpoints for managing studio scenes" }, { "name": "Users", "description": "Endpoints for managing users" }, { "name": "WebhookEvents", "description": "Endpoints for managing webhook events" }, { "name": "WebhookLogs", "description": "Endpoints for managing webhook logs" }, { "name": "WhiteboardComments", "description": "Endpoints for managing comments on whiteboards" }, { "name": "Whiteboards", "description": "Endpoints for managing whiteboards" }, { "name": "WhiteboardPostComments", "description": "Endpoints for managing comments on whiteboard posts" }, { "name": "WhiteboardPosts", "description": "Endpoints for managing whiteboard posts" }, { "name": "WhiteboardPreviews", "description": "Endpoints for managing whiteboard previews" }, { "name": "Workspaces", "description": "Endpoints for managing workspaces" }, { "name": "WorkspaceInvites", "description": "Endpoints for managing workspace invitations" }, { "name": "Public", "description": "Public" }, { "name": "Backoffice", "description": "Backoffice" } ], "security": [ { "bearerAuth": [] } ] }