{ "openapi": "3.1.0", "info": { "title": "Adventur AI API", "version": "1.0.0", "description": "Generated from defineEndpoint route definitions." }, "servers": [ { "url": "https://api.adventur.ai" } ], "tags": [ { "name": "agents" }, { "name": "ai" }, { "name": "billing" }, { "name": "branding" }, { "name": "context" }, { "name": "engagement" }, { "name": "home" }, { "name": "inspiration" }, { "name": "invitations" }, { "name": "launch" }, { "name": "marketing" }, { "name": "members" }, { "name": "notifications" }, { "name": "openapi" }, { "name": "orgs" }, { "name": "public" }, { "name": "strategy" }, { "name": "thoughts" }, { "name": "users" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/v1/context/oauth/notion/callback": { "get": { "operationId": "get_v1_context_oauth_notion_callback", "summary": "GET /v1/context/oauth/notion/callback", "description": "Notion OAuth callback for context sources", "tags": [ "context" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notion OAuth callback for context sources", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/invitations/accept": { "post": { "operationId": "post_v1_invitations_accept", "summary": "POST /v1/invitations/accept", "description": "POST /v1/invitations/accept", "tags": [ "invitations" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "POST /v1/invitations/accept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "orgId": { "type": "string", "format": "uuid" }, "orgSlug": { "type": "string" }, "orgName": { "type": "string" } }, "required": [ "orgId", "orgSlug", "orgName" ] } }, "required": [ "data" ] } } } } } } }, "/v1/marketing/oauth/bluesky/callback": { "get": { "operationId": "get_v1_marketing_oauth_bluesky_callback", "summary": "GET /v1/marketing/oauth/bluesky/callback", "description": "GET /v1/marketing/oauth/bluesky/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "iss", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/bluesky/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/bluesky/client-metadata": { "get": { "operationId": "get_v1_marketing_oauth_bluesky_client_metadata", "summary": "GET /v1/marketing/oauth/bluesky/client-metadata", "description": "Client metadata for signing in with Bluesky (AT Protocol OAuth).", "tags": [ "marketing" ], "responses": { "200": { "description": "Client metadata for signing in with Bluesky (AT Protocol OAuth).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/facebook/callback": { "get": { "operationId": "get_v1_marketing_oauth_facebook_callback", "summary": "GET /v1/marketing/oauth/facebook/callback", "description": "GET /v1/marketing/oauth/facebook/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/facebook/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/instagram/callback": { "get": { "operationId": "get_v1_marketing_oauth_instagram_callback", "summary": "GET /v1/marketing/oauth/instagram/callback", "description": "GET /v1/marketing/oauth/instagram/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/instagram/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/linkedin/callback": { "get": { "operationId": "get_v1_marketing_oauth_linkedin_callback", "summary": "GET /v1/marketing/oauth/linkedin/callback", "description": "GET /v1/marketing/oauth/linkedin/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/linkedin/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/linkedin-pages/callback": { "get": { "operationId": "get_v1_marketing_oauth_linkedin_pages_callback", "summary": "GET /v1/marketing/oauth/linkedin-pages/callback", "description": "LinkedIn Page sign-in callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "LinkedIn Page sign-in callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/reddit/callback": { "get": { "operationId": "get_v1_marketing_oauth_reddit_callback", "summary": "GET /v1/marketing/oauth/reddit/callback", "description": "GET /v1/marketing/oauth/reddit/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/reddit/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/threads/callback": { "get": { "operationId": "get_v1_marketing_oauth_threads_callback", "summary": "GET /v1/marketing/oauth/threads/callback", "description": "GET /v1/marketing/oauth/threads/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/threads/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/tiktok/callback": { "get": { "operationId": "get_v1_marketing_oauth_tiktok_callback", "summary": "GET /v1/marketing/oauth/tiktok/callback", "description": "GET /v1/marketing/oauth/tiktok/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/tiktok/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/x/callback": { "get": { "operationId": "get_v1_marketing_oauth_x_callback", "summary": "GET /v1/marketing/oauth/x/callback", "description": "GET /v1/marketing/oauth/x/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/x/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/marketing/oauth/youtube/callback": { "get": { "operationId": "get_v1_marketing_oauth_youtube_callback", "summary": "GET /v1/marketing/oauth/youtube/callback", "description": "GET /v1/marketing/oauth/youtube/callback", "tags": [ "marketing" ], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/marketing/oauth/youtube/callback", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/openapi.json": { "get": { "operationId": "get_v1_openapi_json", "summary": "GET /v1/openapi.json", "description": "Return the generated OpenAPI specification.", "tags": [ "openapi" ], "responses": { "200": { "description": "Return the generated OpenAPI specification.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/orgs/{orgId}/agent-runs/{runId}/steps": { "get": { "operationId": "get_v1_orgs_orgId_agent_runs_runId_steps", "summary": "List the steps of an agent run", "description": "Returns the model rounds, tool calls and sub-agents recorded for one run, oldest first. This is how a background run reports progress — it has no event stream to subscribe to.", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns the model rounds, tool calls and sub-agents recorded for one run, oldest first. This is how a background run reports progress — it has no event stream to subscribe to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "traceId": { "type": "string" }, "parentStepId": { "type": "string", "nullable": true }, "role": { "type": "string" }, "kind": { "type": "string", "enum": [ "model_round", "tool_call", "subagent" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed" ] }, "label": { "type": "string", "nullable": true }, "input": { "type": "object", "additionalProperties": {}, "nullable": true }, "output": { "type": "string", "nullable": true }, "reasoningSummary": { "type": "string", "nullable": true }, "promptTokens": { "type": "integer" }, "completionTokens": { "type": "integer" }, "reasoningTokens": { "type": "integer" }, "durationMs": { "type": "integer", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "traceId", "parentStepId", "role", "kind", "status", "label", "input", "output", "reasoningSummary", "promptTokens", "completionTokens", "reasoningTokens", "durationMs", "errorMessage", "createdAt" ] } } }, "required": [ "items" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/agent-runs": { "get": { "operationId": "get_v1_orgs_orgId_agent_runs", "summary": "List durable agent runs", "description": "Returns recent AGENT-01 durable job runs for the workspace (queued, running, succeeded, failed).", "tags": [ "agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] } }, { "name": "jobType", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns recent AGENT-01 durable job runs for the workspace (queued, running, succeeded, failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "jobType": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "payload": { "type": "object", "additionalProperties": {} }, "resultSummary": { "type": "object", "additionalProperties": {}, "nullable": true }, "attemptCount": { "type": "integer" }, "maxAttempts": { "type": "integer" }, "idempotencyKey": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "costCredits": { "type": "number", "nullable": true }, "estimatedCostMilliUsd": { "type": "number", "nullable": true }, "createdByUserId": { "type": "string", "format": "uuid", "nullable": true }, "startedAt": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "jobType", "status", "payload", "resultSummary", "attemptCount", "maxAttempts", "idempotencyKey", "errorMessage", "costCredits", "estimatedCostMilliUsd", "createdByUserId", "startedAt", "completedAt", "createdAt", "updatedAt" ] } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [ "items", "total", "page", "limit" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/ai/content/generate": { "post": { "operationId": "post_v1_orgs_orgId_ai_content_generate", "summary": "POST /v1/orgs/{orgId}/ai/content/generate", "description": "POST /v1/orgs/{orgId}/ai/content/generate", "tags": [ "ai" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/ai/content/generate", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" } }, "required": [ "result", "creditsUsed", "remainingCredits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/ai/summarize": { "post": { "operationId": "post_v1_orgs_orgId_ai_summarize", "summary": "POST /v1/orgs/{orgId}/ai/summarize", "description": "POST /v1/orgs/{orgId}/ai/summarize", "tags": [ "ai" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/ai/summarize", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" } }, "required": [ "result", "creditsUsed", "remainingCredits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/automation/x/rules": { "get": { "operationId": "get_v1_orgs_orgId_automation_x_rules", "summary": "Get X automation rules", "description": "The workspace's rules for looking after its own published X posts: reposting the ones that did well (autoRepost) and deleting the ones that didn't (autoDelete). Null means that rule has never been set up.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace's rules for looking after its own published X posts: reposting the ones that did well (autoRepost) and deleting the ones that didn't (autoDelete). Null means that rule has never been set up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "autoRepost": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "const": "threshold", "type": "string" }, "minImpressions": { "type": "integer", "nullable": true }, "minLikes": { "type": "integer", "nullable": true }, "minEngagementRate": { "type": "number", "nullable": true } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "const": "top_n", "type": "string" }, "n": { "type": "integer" }, "rankBy": { "type": "string", "enum": [ "impressions", "likes", "engagement" ] } }, "required": [ "mode" ] } ] }, "cooldownHoursPerPost": { "type": "integer" }, "maxRepostsPerPost": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "action": { "const": "retweet", "type": "string" }, "dryRun": { "type": "boolean" } }, "nullable": true }, "autoDelete": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": {}, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "maxImpressions": { "type": "integer", "nullable": true }, "maxLikes": { "type": "integer", "nullable": true }, "requireMetricsFetched": { "const": true, "type": "boolean" }, "metricsMaxAgeHours": { "type": "integer" }, "skipIfRepliesGte": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "dryRun": { "type": "boolean" } }, "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "updatedBy": { "type": "string", "nullable": true } }, "required": [ "autoRepost", "autoDelete", "updatedAt", "updatedBy" ] } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "put_v1_orgs_orgId_automation_x_rules", "summary": "Update X automation rules", "description": "Sets the auto-repost and auto-delete rules for the workspace's own published X posts. One kind at a time: a kind left out keeps its saved rule, and fields left out of a kind keep their values, or take safe defaults (off, dry run) the first time. Passing null for a threshold clears it.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autoRepost": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "const": "threshold", "type": "string" }, "minImpressions": { "type": "integer", "nullable": true }, "minLikes": { "type": "integer", "nullable": true }, "minEngagementRate": { "type": "number", "nullable": true } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "const": "top_n", "type": "string" }, "n": { "type": "integer" }, "rankBy": { "type": "string", "enum": [ "impressions", "likes", "engagement" ] } }, "required": [ "mode" ] } ] }, "cooldownHoursPerPost": { "type": "integer" }, "maxRepostsPerPost": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "action": { "const": "retweet", "type": "string" }, "dryRun": { "type": "boolean" } } }, "autoDelete": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": {}, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "maxImpressions": { "type": "integer", "nullable": true }, "maxLikes": { "type": "integer", "nullable": true }, "requireMetricsFetched": { "const": true, "type": "boolean" }, "metricsMaxAgeHours": { "type": "integer" }, "skipIfRepliesGte": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "dryRun": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Sets the auto-repost and auto-delete rules for the workspace's own published X posts. One kind at a time: a kind left out keeps its saved rule, and fields left out of a kind keep their values, or take safe defaults (off, dry run) the first time. Passing null for a threshold clears it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "autoRepost": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "const": "threshold", "type": "string" }, "minImpressions": { "type": "integer", "nullable": true }, "minLikes": { "type": "integer", "nullable": true }, "minEngagementRate": { "type": "number", "nullable": true } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "const": "top_n", "type": "string" }, "n": { "type": "integer" }, "rankBy": { "type": "string", "enum": [ "impressions", "likes", "engagement" ] } }, "required": [ "mode" ] } ] }, "cooldownHoursPerPost": { "type": "integer" }, "maxRepostsPerPost": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "action": { "const": "retweet", "type": "string" }, "dryRun": { "type": "boolean" } }, "nullable": true }, "autoDelete": { "type": "object", "properties": { "channel": { "const": "x", "type": "string" }, "socialAccountId": {}, "enabled": { "type": "boolean" }, "minAgeHours": { "type": "integer" }, "maxAgeDays": { "type": "integer" }, "maxImpressions": { "type": "integer", "nullable": true }, "maxLikes": { "type": "integer", "nullable": true }, "requireMetricsFetched": { "const": true, "type": "boolean" }, "metricsMaxAgeHours": { "type": "integer" }, "skipIfRepliesGte": { "type": "integer" }, "maxActionsPerDay": { "type": "integer" }, "dryRun": { "type": "boolean" } }, "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "updatedBy": { "type": "string", "nullable": true } }, "required": [ "autoRepost", "autoDelete", "updatedAt", "updatedBy" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/automation/x/run": { "post": { "operationId": "post_v1_orgs_orgId_automation_x_run", "summary": "Run X automation now", "description": "Applies the workspace's X automation rules to its own published X posts straight away, instead of waiting for the nightly sweep. Only rules that are switched on are considered, and a rule in dry run records what it would have done without touching X.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "string", "enum": [ "auto_repost", "auto_delete" ] } }, "dryRun": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Applies the workspace's X automation rules to its own published X posts straight away, instead of waiting for the nightly sweep. Only rules that are switched on are considered, and a rule in dry run records what it would have done without touching X.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "auto_repost", "auto_delete" ] } }, "counts": { "type": "object", "properties": { "evaluated": { "type": "integer" }, "matched": { "type": "integer" }, "acted": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "evaluated", "matched", "acted", "skipped", "failed" ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "auto_repost", "auto_delete" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "sourcePostId": { "type": "string", "format": "uuid", "nullable": true }, "externalTweetId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "planned", "succeeded", "failed", "skipped" ] }, "reason": { "type": "string", "nullable": true }, "dryRun": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "kind", "socialAccountId", "sourcePostId", "externalTweetId", "status", "reason", "dryRun", "error", "createdAt" ] } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "dryRun", "kinds", "counts", "actions", "warnings" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/automation/x/runs": { "get": { "operationId": "get_v1_orgs_orgId_automation_x_runs", "summary": "List what X automation decided", "description": "What the workspace's X automation rules decided about its own published posts, newest first: reposted, deleted, left alone, or — in dry run — what would have happened.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "What the workspace's X automation rules decided about its own published posts, newest first: reposted, deleted, left alone, or — in dry run — what would have happened.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "auto_repost", "auto_delete" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "sourcePostId": { "type": "string", "format": "uuid", "nullable": true }, "externalTweetId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "planned", "succeeded", "failed", "skipped" ] }, "reason": { "type": "string", "nullable": true }, "dryRun": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "kind", "socialAccountId", "sourcePostId", "externalTweetId", "status", "reason", "dryRun", "error", "createdAt" ] } } }, "required": [ "items" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/autonomy": { "get": { "operationId": "get_v1_orgs_orgId_autonomy", "summary": "Get workspace autonomy mode", "description": "Returns Approval/Trusted mode for the workspace. Autopilot is not selectable in private alpha.", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns Approval/Trusted mode for the workspace. Autopilot is not selectable in private alpha.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "autonomyMode": { "type": "string", "enum": [ "approval", "trusted" ] }, "autopilotAvailable": { "const": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "autonomyMode", "autopilotAvailable", "description" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_autonomy", "summary": "Update workspace autonomy mode", "description": "Sets Approval or Trusted mode. Autopilot writes are rejected. Owner/admin only.", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autonomyMode": { "type": "string", "enum": [ "approval", "trusted" ] } }, "required": [ "autonomyMode" ] } } } }, "responses": { "200": { "description": "Sets Approval or Trusted mode. Autopilot writes are rejected. Owner/admin only.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "autonomyMode": { "type": "string", "enum": [ "approval", "trusted" ] }, "autopilotAvailable": { "const": false, "type": "boolean" }, "description": { "type": "string" } }, "required": [ "autonomyMode", "autopilotAvailable", "description" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/change-plan": { "post": { "operationId": "post_v1_orgs_orgId_billing_change_plan", "summary": "POST /v1/orgs/{orgId}/billing/change-plan", "description": "POST /v1/orgs/{orgId}/billing/change-plan", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priceId": { "type": "string" } }, "required": [ "priceId" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/billing/change-plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "updated", "message" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/checkout-data": { "get": { "operationId": "get_v1_orgs_orgId_billing_checkout_data", "summary": "GET /v1/orgs/{orgId}/billing/checkout-data", "description": "GET /v1/orgs/{orgId}/billing/checkout-data", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-forwarded-for", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing/checkout-data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "paddleCustomerId": { "type": "string", "nullable": true }, "trialDurationDays": { "type": "integer" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "paddlePriceId": { "type": "string", "nullable": true }, "paddlePriceIdAnnual": { "type": "string", "nullable": true }, "monthlyPrice": { "type": "number", "nullable": true }, "annualPrice": { "type": "number", "nullable": true }, "monthlyCredits": { "type": "number" }, "teamsEnabled": { "type": "boolean" }, "maxMembers": { "type": "number" }, "localizedCurrencyCode": { "type": "string", "nullable": true }, "localizedMonthlyPrice": { "type": "number", "nullable": true }, "localizedMonthlyPriceFormatted": { "type": "string", "nullable": true }, "localizedAnnualPrice": { "type": "number", "nullable": true }, "localizedAnnualPriceFormatted": { "type": "string", "nullable": true } }, "required": [ "key", "name", "paddlePriceId", "paddlePriceIdAnnual", "monthlyPrice", "annualPrice", "monthlyCredits", "teamsEnabled", "maxMembers" ] } }, "creditPacks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "paddlePriceId": { "type": "string", "nullable": true }, "credits": { "type": "number" }, "price": { "type": "number" }, "localizedCurrencyCode": { "type": "string", "nullable": true }, "localizedPrice": { "type": "number", "nullable": true }, "localizedPriceFormatted": { "type": "string", "nullable": true } }, "required": [ "key", "name", "paddlePriceId", "credits", "price" ] } } }, "required": [ "paddleCustomerId", "trialDurationDays", "plans", "creditPacks" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/credits/usage": { "get": { "operationId": "get_v1_orgs_orgId_billing_credits_usage", "summary": "GET /v1/orgs/{orgId}/billing/credits/usage", "description": "GET /v1/orgs/{orgId}/billing/credits/usage", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "metricKey", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "feature", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "createdAtFrom", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "createdAtTo", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing/credits/usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "metricKey": { "type": "string" }, "quantity": { "type": "number" }, "type": { "type": "string", "nullable": true }, "feature": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "inputTokens": { "type": "number", "nullable": true }, "outputTokens": { "type": "number", "nullable": true }, "totalTokens": { "type": "number", "nullable": true }, "amountUsed": { "type": "number" }, "creditsUsedMilli": { "type": "number", "nullable": true }, "pricingVersion": { "type": "string", "nullable": true }, "usedFallbackEstimate": { "type": "boolean" }, "monthlyCreditsAfter": { "type": "number", "nullable": true }, "purchasedCreditsAfter": { "type": "number", "nullable": true }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "metricKey", "quantity", "type", "feature", "provider", "model", "inputTokens", "outputTokens", "totalTokens", "amountUsed", "creditsUsedMilli", "pricingVersion", "usedFallbackEstimate", "monthlyCreditsAfter", "purchasedCreditsAfter", "metadata", "createdAt" ] } }, "metadata": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNext", "hasPrev" ] } }, "required": [ "data", "metadata" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing": { "get": { "operationId": "get_v1_orgs_orgId_billing", "summary": "GET /v1/orgs/{orgId}/billing", "description": "GET /v1/orgs/{orgId}/billing", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "name": { "type": "string" }, "monthlyPrice": { "type": "number", "nullable": true }, "monthlyCredits": { "type": "number" }, "teamsEnabled": { "type": "boolean" }, "maxMembers": { "type": "number" } }, "required": [ "id", "key", "name", "monthlyPrice", "monthlyCredits", "teamsEnabled", "maxMembers" ], "nullable": true }, "subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "pausing", "paused", "past_due", "canceled", "trialing" ] }, "accessState": { "type": "string", "enum": [ "full", "read_only" ] }, "trialEndsAt": { "type": "string", "nullable": true }, "trialDaysRemaining": { "type": "integer", "nullable": true }, "isTrialExpired": { "type": "boolean" }, "canChangePlan": { "type": "boolean" }, "canPause": { "type": "boolean" }, "pastDueSince": { "type": "string", "nullable": true }, "graceEndsAt": { "type": "string", "nullable": true }, "billingInterval": { "type": "string" }, "currentPeriodStart": { "type": "string", "nullable": true }, "currentPeriodEnd": { "type": "string", "nullable": true }, "cancelAtPeriodEnd": { "type": "boolean", "nullable": true }, "paddleCustomerId": { "type": "string", "nullable": true }, "hasPaddleSubscription": { "type": "boolean" } }, "required": [ "id", "status", "accessState", "trialEndsAt", "trialDaysRemaining", "isTrialExpired", "canChangePlan", "canPause", "pastDueSince", "graceEndsAt", "billingInterval", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "paddleCustomerId", "hasPaddleSubscription" ], "nullable": true }, "trialDurationDays": { "type": "integer" }, "creditBalance": { "type": "object", "properties": { "monthly": { "type": "number" }, "rollover": { "type": "number" }, "purchased": { "type": "number" }, "allowance": { "type": "number" }, "total": { "type": "number" } }, "required": [ "monthly", "purchased", "allowance", "total" ] }, "usageSummary": { "type": "object", "properties": { "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "periodUsedCredits": { "type": "number" }, "periodAllowanceCredits": { "type": "number" }, "periodPurchasedCredits": { "type": "number" }, "periodBudgetCredits": { "type": "number" }, "periodRemainingCredits": { "type": "number" }, "usagePercent": { "type": "number" } }, "required": [ "periodStart", "periodEnd", "periodUsedCredits", "periodAllowanceCredits", "periodPurchasedCredits", "periodBudgetCredits", "periodRemainingCredits", "usagePercent" ] }, "creditActionCosts": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "credits": { "type": "integer" } }, "required": [ "key", "label", "description", "credits" ] } }, "paddleCreditBalance": { "type": "array", "items": { "type": "object", "properties": { "currencyCode": { "type": "string" }, "availableCents": { "type": "number" } }, "required": [ "currencyCode", "availableCents" ] } }, "recentCreditTransactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "amount": { "type": "number" }, "monthlyCreditsAfter": { "type": "number" }, "purchasedCreditsAfter": { "type": "number" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "amount", "monthlyCreditsAfter", "purchasedCreditsAfter", "metadata", "createdAt" ] } }, "recentBillingTransactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "invoiceUrl": { "type": "string", "nullable": true }, "paidAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "amount", "currency", "status", "invoiceUrl", "paidAt", "createdAt" ] } }, "recentSubscriptionEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "pausing", "paused", "resumed" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "createdAt" ] } }, "recentInvoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "invoiceUrl": { "type": "string", "nullable": true }, "paidAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "total", "currency", "invoiceUrl", "paidAt", "createdAt" ] } } }, "required": [ "plan", "subscription", "trialDurationDays", "creditBalance", "usageSummary", "creditActionCosts", "recentCreditTransactions", "recentBillingTransactions", "recentSubscriptionEvents", "recentInvoices" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/invoices": { "get": { "operationId": "get_v1_orgs_orgId_billing_invoices", "summary": "GET /v1/orgs/{orgId}/billing/invoices", "description": "GET /v1/orgs/{orgId}/billing/invoices", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "amount", "status" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string" }, "createdAtFrom": { "type": "string" }, "createdAtTo": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "eq", "in" ] }, "createdAtFrom": { "type": "string", "enum": [ "gte" ] }, "createdAtTo": { "type": "string", "enum": [ "lte" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing/invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "invoiceUrl": { "type": "string", "nullable": true }, "paidAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "status", "total", "currency", "invoiceUrl", "paidAt", "createdAt" ] } }, "metadata": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNext", "hasPrev" ] } }, "required": [ "data", "metadata" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/subscription/cancel": { "post": { "operationId": "post_v1_orgs_orgId_billing_subscription_cancel", "summary": "POST /v1/orgs/{orgId}/billing/subscription/cancel", "description": "Cancel the org subscription. Trials cancel immediately; paid subscriptions cancel at period end.", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancel the org subscription. Trials cancel immediately; paid subscriptions cancel at period end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelAtPeriodEnd": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "cancelAtPeriodEnd", "message" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/subscription/pause": { "post": { "operationId": "post_v1_orgs_orgId_billing_subscription_pause", "summary": "POST /v1/orgs/{orgId}/billing/subscription/pause", "description": "Pause the org subscription at period end. Not available while the subscription is trialing.", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pause the org subscription at period end. Not available while the subscription is trialing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/subscription/resume": { "post": { "operationId": "post_v1_orgs_orgId_billing_subscription_resume", "summary": "POST /v1/orgs/{orgId}/billing/subscription/resume", "description": "POST /v1/orgs/{orgId}/billing/subscription/resume", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "POST /v1/orgs/{orgId}/billing/subscription/resume", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/subscription/update-payment": { "post": { "operationId": "post_v1_orgs_orgId_billing_subscription_update_payment", "summary": "POST /v1/orgs/{orgId}/billing/subscription/update-payment", "description": "Create a Paddle transaction (or management URL) so the customer can update their payment method.", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Create a Paddle transaction (or management URL) so the customer can update their payment method.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "transactionId": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "transactionId" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/transactions/{transactionId}/invoice": { "get": { "operationId": "get_v1_orgs_orgId_billing_transactions_transactionId_invoice", "summary": "GET /v1/orgs/{orgId}/billing/transactions/{transactionId}/invoice", "description": "GET /v1/orgs/{orgId}/billing/transactions/{transactionId}/invoice", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing/transactions/{transactionId}/invoice", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/billing/transactions": { "get": { "operationId": "get_v1_orgs_orgId_billing_transactions", "summary": "GET /v1/orgs/{orgId}/billing/transactions", "description": "GET /v1/orgs/{orgId}/billing/transactions", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "amount", "status", "type" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string" }, "type": { "type": "string" }, "createdAtFrom": { "type": "string" }, "createdAtTo": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "eq", "in" ] }, "type": { "type": "string", "enum": [ "eq", "in" ] }, "createdAtFrom": { "type": "string", "enum": [ "gte" ] }, "createdAtTo": { "type": "string", "enum": [ "lte" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/billing/transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "invoiceUrl": { "type": "string", "nullable": true }, "paidAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "type", "amount", "currency", "status", "invoiceUrl", "paidAt", "createdAt" ] } }, "metadata": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNext": { "type": "boolean" }, "hasPrev": { "type": "boolean" } }, "required": [ "page", "limit", "total", "totalPages", "hasNext", "hasPrev" ] } }, "required": [ "data", "metadata" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/brand/kit": { "get": { "operationId": "get_v1_orgs_orgId_brand_kit", "summary": "Get the brand kit", "description": "The workspace's brand colours, fonts, tagline and logo used for branded visuals, and what's missing.", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace's brand colours, fonts, tagline and logo used for branded visuals, and what's missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "primary": { "type": "string", "nullable": true }, "secondary": { "type": "string", "nullable": true }, "accent": { "type": "string", "nullable": true }, "background": { "type": "string", "nullable": true } }, "required": [ "primary", "secondary", "accent", "background" ] }, "headingFont": { "type": "string", "nullable": true }, "bodyFont": { "type": "string", "nullable": true }, "logo": { "type": "object", "properties": { "assetId": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "contentType": { "type": "string", "nullable": true } }, "required": [ "assetId", "url", "sourceUrl", "width", "height", "contentType" ], "nullable": true }, "tagline": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "colors", "logo", "fonts" ] } } }, "required": [ "colors", "headingFont", "bodyFont", "logo", "tagline", "website", "updatedAt", "missing" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_brand_kit", "summary": "Update the brand kit", "description": "Sets any of the brand colours, fonts, logo, tagline and website. Omitted fields are unchanged and null clears one. A logo link is downloaded, checked and stored in the workspace (SVGs are sanitised first). Every field is checked before anything is saved: a refused call returns 422 with one error per bad field.", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "primary": { "type": "string", "nullable": true }, "secondary": { "type": "string", "nullable": true }, "accent": { "type": "string", "nullable": true }, "background": { "type": "string", "nullable": true } } }, "headingFont": { "type": "string", "nullable": true }, "bodyFont": { "type": "string", "nullable": true }, "logo": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, { "type": "object", "properties": { "assetId": { "type": "string" } }, "required": [ "assetId" ] } ], "nullable": true }, "tagline": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "ifUpdatedAt": { "type": "string" }, "dryRun": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Sets any of the brand colours, fonts, logo, tagline and website. Omitted fields are unchanged and null clears one. A logo link is downloaded, checked and stored in the workspace (SVGs are sanitised first). Every field is checked before anything is saved: a refused call returns 422 with one error per bad field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "saved": { "type": "boolean" }, "kit": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "primary": { "type": "string", "nullable": true }, "secondary": { "type": "string", "nullable": true }, "accent": { "type": "string", "nullable": true }, "background": { "type": "string", "nullable": true } }, "required": [ "primary", "secondary", "accent", "background" ] }, "headingFont": { "type": "string", "nullable": true }, "bodyFont": { "type": "string", "nullable": true }, "logo": { "type": "object", "properties": { "assetId": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "contentType": { "type": "string", "nullable": true } }, "required": [ "assetId", "url", "sourceUrl", "width", "height", "contentType" ], "nullable": true }, "tagline": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "colors", "logo", "fonts" ] } } }, "required": [ "colors", "headingFont", "bodyFont", "logo", "tagline", "website", "updatedAt", "missing" ] }, "changed": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "code", "message" ] } }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "colors", "logo", "fonts" ] } }, "previewHint": { "type": "string" } }, "required": [ "saved", "kit", "changed", "warnings", "missing", "previewHint" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/brand/kit/website": { "get": { "operationId": "get_v1_orgs_orgId_brand_kit_website", "summary": "Find brand kit candidates on a website", "description": "Reads a public website and lists colours, logos, images and fonts that could go in the brand kit, with a suggested kit. Saves nothing.", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reads a public website and lists colours, logos, images and fonts that could go in the brand kit, with a suggested kit. Saves nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "websiteUrl": { "type": "string" }, "reachable": { "type": "boolean" }, "siteName": { "type": "string", "nullable": true }, "tagline": { "type": "string", "nullable": true }, "colors": { "type": "array", "items": { "type": "object", "properties": { "hex": { "type": "string" }, "source": { "type": "string", "enum": [ "theme-color", "css-variable", "stylesheet", "inline" ] }, "detail": { "type": "string", "nullable": true }, "uses": { "type": "integer" }, "neutral": { "type": "boolean" } }, "required": [ "hex", "source", "detail", "uses", "neutral" ] } }, "logos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string", "enum": [ "structured-data", "og:logo", "img", "apple-touch-icon", "icon" ] } }, "required": [ "url", "source" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string", "enum": [ "og:image", "twitter:image" ] } }, "required": [ "url", "source" ] } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string" }, "source": { "type": "string", "enum": [ "google-fonts", "css" ] } }, "required": [ "family", "source" ] } }, "suggestion": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" } } }, "headingFont": { "type": "string" }, "bodyFont": { "type": "string" }, "logo": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "website": { "type": "string" } }, "required": [ "website" ] } }, "required": [ "websiteUrl", "reachable", "siteName", "tagline", "colors", "logos", "images", "fonts", "suggestion" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/brand/profile/from-website": { "post": { "operationId": "post_v1_orgs_orgId_brand_profile_from_website", "summary": "POST /v1/orgs/{orgId}/brand/profile/from-website", "description": "POST /v1/orgs/{orgId}/brand/profile/from-website", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string" } }, "required": [ "websiteUrl" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/brand/profile/from-website", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "nullable": true }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "primaryFont": { "type": "string", "nullable": true }, "secondaryFont": { "type": "string", "nullable": true }, "colorPalette": { "type": "array", "items": { "type": "string" } }, "backgroundColor": { "type": "string", "nullable": true }, "logoAsset": { "type": "object", "properties": { "assetId": { "type": "string" }, "contentType": { "type": "string" }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "sourceAssetId": { "type": "string", "nullable": true } }, "required": [ "assetId", "contentType", "width", "height" ], "nullable": true }, "kitUpdatedAt": { "type": "string", "nullable": true }, "tagline": { "type": "string", "nullable": true }, "mission": { "type": "string", "nullable": true }, "voice": { "type": "object", "properties": { "tone": { "type": "string" }, "personalityTraits": { "type": "array", "items": { "type": "string" } }, "writingGuidelines": { "type": "array", "items": { "type": "string" } }, "bannedPhrases": { "type": "array", "items": { "type": "string" } } }, "required": [ "tone", "personalityTraits", "writingGuidelines", "bannedPhrases" ] }, "businessOutline": { "type": "object", "properties": { "overview": { "type": "string" }, "productsOrServices": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "valueProposition": { "type": "string" }, "differentiators": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "productsOrServices", "targetAudience", "valueProposition", "differentiators" ] }, "brandType": { "type": "string", "enum": [ "personal", "business", "unknown" ] }, "identity": { "type": "string", "nullable": true }, "expertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "opinions": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "private", "restricted" ] } }, "required": [ "id", "text" ] } }, "knowledgeItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "claim", "fact", "opinion", "preference", "topic" ] }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "durability": { "type": "string", "enum": [ "durable", "time_sensitive" ] }, "provenance": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "user", "inferred", "imported", "learned" ] }, "sourceType": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "sourceExternalId": { "type": "string", "nullable": true }, "fetchedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "userSupplied": { "type": "boolean" } }, "required": [ "origin" ] }, "confirmed": { "type": "boolean" } }, "required": [ "id", "kind", "text", "provenance" ] } }, "preferenceSignals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signal": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "edit", "reject", "explicit" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "occurrences": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "promoted": { "type": "boolean" } }, "required": [ "id", "signal", "kind", "lastSeenAt" ] } }, "profileDisclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "confirmedAt": { "type": "string", "nullable": true }, "lastInferredAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true } } } }, "required": [ "websiteUrl", "logoUrl", "primaryFont", "secondaryFont", "colorPalette", "tagline", "mission", "voice", "businessOutline" ] }, "source": { "type": "string", "enum": [ "ai", "heuristic" ] } }, "required": [ "profile", "source" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/brand/profile": { "get": { "operationId": "get_v1_orgs_orgId_brand_profile", "summary": "GET /v1/orgs/{orgId}/brand/profile", "description": "GET /v1/orgs/{orgId}/brand/profile", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/brand/profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "nullable": true }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "primaryFont": { "type": "string", "nullable": true }, "secondaryFont": { "type": "string", "nullable": true }, "colorPalette": { "type": "array", "items": { "type": "string" } }, "backgroundColor": { "type": "string", "nullable": true }, "logoAsset": { "type": "object", "properties": { "assetId": { "type": "string" }, "contentType": { "type": "string" }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "sourceAssetId": { "type": "string", "nullable": true } }, "required": [ "assetId", "contentType", "width", "height" ], "nullable": true }, "kitUpdatedAt": { "type": "string", "nullable": true }, "tagline": { "type": "string", "nullable": true }, "mission": { "type": "string", "nullable": true }, "voice": { "type": "object", "properties": { "tone": { "type": "string" }, "personalityTraits": { "type": "array", "items": { "type": "string" } }, "writingGuidelines": { "type": "array", "items": { "type": "string" } }, "bannedPhrases": { "type": "array", "items": { "type": "string" } } }, "required": [ "tone", "personalityTraits", "writingGuidelines", "bannedPhrases" ] }, "businessOutline": { "type": "object", "properties": { "overview": { "type": "string" }, "productsOrServices": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "valueProposition": { "type": "string" }, "differentiators": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "productsOrServices", "targetAudience", "valueProposition", "differentiators" ] }, "brandType": { "type": "string", "enum": [ "personal", "business", "unknown" ] }, "identity": { "type": "string", "nullable": true }, "expertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "opinions": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "private", "restricted" ] } }, "required": [ "id", "text" ] } }, "knowledgeItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "claim", "fact", "opinion", "preference", "topic" ] }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "durability": { "type": "string", "enum": [ "durable", "time_sensitive" ] }, "provenance": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "user", "inferred", "imported", "learned" ] }, "sourceType": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "sourceExternalId": { "type": "string", "nullable": true }, "fetchedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "userSupplied": { "type": "boolean" } }, "required": [ "origin" ] }, "confirmed": { "type": "boolean" } }, "required": [ "id", "kind", "text", "provenance" ] } }, "preferenceSignals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signal": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "edit", "reject", "explicit" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "occurrences": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "promoted": { "type": "boolean" } }, "required": [ "id", "signal", "kind", "lastSeenAt" ] } }, "profileDisclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "confirmedAt": { "type": "string", "nullable": true }, "lastInferredAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true } } } }, "required": [ "websiteUrl", "logoUrl", "primaryFont", "secondaryFont", "colorPalette", "tagline", "mission", "voice", "businessOutline" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_brand_profile", "summary": "PATCH /v1/orgs/{orgId}/brand/profile", "description": "PATCH /v1/orgs/{orgId}/brand/profile", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "nullable": true }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "primaryFont": { "type": "string", "nullable": true }, "secondaryFont": { "type": "string", "nullable": true }, "colorPalette": { "type": "array", "items": { "type": "string" } }, "tagline": { "type": "string", "nullable": true }, "mission": { "type": "string", "nullable": true }, "voice": { "type": "object", "properties": { "tone": { "type": "string" }, "personalityTraits": { "type": "array", "items": { "type": "string" } }, "writingGuidelines": { "type": "array", "items": { "type": "string" } }, "bannedPhrases": { "type": "array", "items": { "type": "string" } } } }, "businessOutline": { "type": "object", "properties": { "overview": { "type": "string" }, "productsOrServices": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "valueProposition": { "type": "string" }, "differentiators": { "type": "array", "items": { "type": "string" } } } }, "brandType": { "type": "string", "enum": [ "personal", "business", "unknown" ] }, "identity": { "type": "string", "nullable": true }, "expertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "opinions": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "private", "restricted" ] } }, "required": [ "id", "text" ] } }, "knowledgeItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "claim", "fact", "opinion", "preference", "topic" ] }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "durability": { "type": "string", "enum": [ "durable", "time_sensitive" ] }, "provenance": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "user", "inferred", "imported", "learned" ] }, "sourceType": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "sourceExternalId": { "type": "string", "nullable": true }, "fetchedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "userSupplied": { "type": "boolean" } }, "required": [ "origin" ] }, "confirmed": { "type": "boolean" } }, "required": [ "id", "kind", "text", "provenance" ] } }, "preferenceSignals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signal": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "edit", "reject", "explicit" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "occurrences": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "promoted": { "type": "boolean" } }, "required": [ "id", "signal", "kind", "lastSeenAt" ] } }, "profileDisclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "confirmedAt": { "type": "string", "nullable": true }, "lastInferredAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true } } }, "confirmBrandContext": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "PATCH /v1/orgs/{orgId}/brand/profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "nullable": true }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "primaryFont": { "type": "string", "nullable": true }, "secondaryFont": { "type": "string", "nullable": true }, "colorPalette": { "type": "array", "items": { "type": "string" } }, "backgroundColor": { "type": "string", "nullable": true }, "logoAsset": { "type": "object", "properties": { "assetId": { "type": "string" }, "contentType": { "type": "string" }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "sourceAssetId": { "type": "string", "nullable": true } }, "required": [ "assetId", "contentType", "width", "height" ], "nullable": true }, "kitUpdatedAt": { "type": "string", "nullable": true }, "tagline": { "type": "string", "nullable": true }, "mission": { "type": "string", "nullable": true }, "voice": { "type": "object", "properties": { "tone": { "type": "string" }, "personalityTraits": { "type": "array", "items": { "type": "string" } }, "writingGuidelines": { "type": "array", "items": { "type": "string" } }, "bannedPhrases": { "type": "array", "items": { "type": "string" } } }, "required": [ "tone", "personalityTraits", "writingGuidelines", "bannedPhrases" ] }, "businessOutline": { "type": "object", "properties": { "overview": { "type": "string" }, "productsOrServices": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "valueProposition": { "type": "string" }, "differentiators": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "productsOrServices", "targetAudience", "valueProposition", "differentiators" ] }, "brandType": { "type": "string", "enum": [ "personal", "business", "unknown" ] }, "identity": { "type": "string", "nullable": true }, "expertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "opinions": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "private", "restricted" ] } }, "required": [ "id", "text" ] } }, "knowledgeItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "claim", "fact", "opinion", "preference", "topic" ] }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "durability": { "type": "string", "enum": [ "durable", "time_sensitive" ] }, "provenance": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "user", "inferred", "imported", "learned" ] }, "sourceType": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "sourceExternalId": { "type": "string", "nullable": true }, "fetchedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "userSupplied": { "type": "boolean" } }, "required": [ "origin" ] }, "confirmed": { "type": "boolean" } }, "required": [ "id", "kind", "text", "provenance" ] } }, "preferenceSignals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signal": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "edit", "reject", "explicit" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "occurrences": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "promoted": { "type": "boolean" } }, "required": [ "id", "signal", "kind", "lastSeenAt" ] } }, "profileDisclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "confirmedAt": { "type": "string", "nullable": true }, "lastInferredAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true } } } }, "required": [ "websiteUrl", "logoUrl", "primaryFont", "secondaryFont", "colorPalette", "tagline", "mission", "voice", "businessOutline" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/documents/{documentId}": { "patch": { "operationId": "patch_v1_orgs_orgId_context_documents_documentId", "summary": "PATCH /v1/orgs/{orgId}/context/documents/{documentId}", "description": "Update a context library document", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] } } } } } }, "responses": { "200": { "description": "Update a context library document", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "externalId": { "type": "string" }, "title": { "type": "string" }, "contentText": { "type": "string" }, "contentUrl": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "syncedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceId", "sourceType", "externalId", "title", "contentText", "contentUrl", "enabled", "disclosure", "syncedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_context_documents_documentId", "summary": "DELETE /v1/orgs/{orgId}/context/documents/{documentId}", "description": "Delete a context library document", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete a context library document", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "externalId": { "type": "string" }, "title": { "type": "string" }, "contentText": { "type": "string" }, "contentUrl": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "syncedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceId", "sourceType", "externalId", "title", "contentText", "contentUrl", "enabled", "disclosure", "syncedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/documents": { "get": { "operationId": "get_v1_orgs_orgId_context_documents", "summary": "GET /v1/orgs/{orgId}/context/documents", "description": "List synced context library documents", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List synced context library documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "externalId": { "type": "string" }, "title": { "type": "string" }, "contentText": { "type": "string" }, "contentUrl": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "syncedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceId", "sourceType", "externalId", "title", "contentText", "contentUrl", "enabled", "disclosure", "syncedAt", "createdAt", "updatedAt" ] } } }, "required": [ "documents" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/sources/{sourceId}": { "delete": { "operationId": "delete_v1_orgs_orgId_context_sources_sourceId", "summary": "DELETE /v1/orgs/{orgId}/context/sources/{sourceId}", "description": "Disconnect a workspace context source", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Disconnect a workspace context source", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "externalWorkspaceId": { "type": "string", "nullable": true }, "workspaceName": { "type": "string", "nullable": true }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceType", "status", "externalWorkspaceId", "workspaceName", "lastSyncedAt", "lastError", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/sources/{sourceId}/pages": { "get": { "operationId": "get_v1_orgs_orgId_context_sources_sourceId_pages", "summary": "GET /v1/orgs/{orgId}/context/sources/{sourceId}/pages", "description": "List Notion pages available for sync into the context library", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List Notion pages available for sync into the context library", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "nullable": true }, "lastEditedTime": { "type": "string", "nullable": true } }, "required": [ "id", "title", "url", "lastEditedTime" ] } } }, "required": [ "pages" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/sources/{sourceId}/sync": { "post": { "operationId": "post_v1_orgs_orgId_context_sources_sourceId_sync", "summary": "POST /v1/orgs/{orgId}/context/sources/{sourceId}/sync", "description": "Sync selected Notion pages into the context library", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pageIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "pageIds" ] } } } }, "responses": { "200": { "description": "Sync selected Notion pages into the context library", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "synced": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "externalId": { "type": "string" }, "title": { "type": "string" }, "contentText": { "type": "string" }, "contentUrl": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "syncedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceId", "sourceType", "externalId", "title", "contentText", "contentUrl", "enabled", "disclosure", "syncedAt", "createdAt", "updatedAt" ] } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "pageId", "error" ] } } }, "required": [ "synced", "failed" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/sources": { "get": { "operationId": "get_v1_orgs_orgId_context_sources", "summary": "GET /v1/orgs/{orgId}/context/sources", "description": "List connected workspace context sources", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List connected workspace context sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "sourceType": { "type": "string", "enum": [ "notion" ] }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "externalWorkspaceId": { "type": "string", "nullable": true }, "workspaceName": { "type": "string", "nullable": true }, "lastSyncedAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "sourceType", "status", "externalWorkspaceId", "workspaceName", "lastSyncedAt", "lastError", "createdAt", "updatedAt" ] } } }, "required": [ "sources" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/context/sources/notion/oauth/start": { "post": { "operationId": "post_v1_orgs_orgId_context_sources_notion_oauth_start", "summary": "POST /v1/orgs/{orgId}/context/sources/notion/oauth/start", "description": "Start Notion OAuth for workspace context library", "tags": [ "context" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string", "format": "uri" }, "linkedinTarget": { "type": "string", "enum": [ "profile", "page" ] }, "blueskyHandle": { "type": "string" } }, "required": [ "redirectUri" ] } } } }, "responses": { "200": { "description": "Start Notion OAuth for workspace context library", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "required": [ "authorizationUrl", "state" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/dms/{conversationId}/draft": { "post": { "operationId": "post_v1_orgs_orgId_dms_conversationId_draft", "summary": "Draft the next DM", "description": "Drafts the next message in a DM conversation in the user's voice: an opener, a reply to their last message, or a follow-up when they haven't answered. Sends nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guidance": { "type": "string" } } } } } }, "responses": { "200": { "description": "Drafts the next message in a DM conversation in the user's voice: an opener, a reply to their last message, or a follow-up when they haven't answered. Sends nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x" ] }, "status": { "type": "string", "enum": [ "your_turn", "waiting", "closed" ] }, "person": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "profileUrl": { "type": "string" } }, "required": [ "handle", "name", "bio", "followers", "profileUrl" ] }, "notes": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" }, "at": { "type": "string" } }, "required": [ "id", "from", "text", "at" ] } }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "draftedAt": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "nullable": true }, "followUpAt": { "type": "string", "nullable": true }, "followUpDue": { "type": "boolean" }, "sendOnXUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "status", "person", "notes", "messages", "draftText", "draftReason", "draftedAt", "lastMessageAt", "followUpAt", "followUpDue", "sendOnXUrl", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/dms/{conversationId}": { "patch": { "operationId": "patch_v1_orgs_orgId_dms_conversationId", "summary": "Update a DM conversation", "description": "Logs a message the other person sent or one the user sent on X, edits the drafted message or notes, or closes or reopens the conversation. Optionally drafts the next message. Sends nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addMessage": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" } }, "required": [ "from", "text" ] }, "notes": { "type": "string" }, "draftText": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "draft": { "type": "boolean" }, "guidance": { "type": "string" } } } } } }, "responses": { "200": { "description": "Logs a message the other person sent or one the user sent on X, edits the drafted message or notes, or closes or reopens the conversation. Optionally drafts the next message. Sends nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x" ] }, "status": { "type": "string", "enum": [ "your_turn", "waiting", "closed" ] }, "person": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "profileUrl": { "type": "string" } }, "required": [ "handle", "name", "bio", "followers", "profileUrl" ] }, "notes": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" }, "at": { "type": "string" } }, "required": [ "id", "from", "text", "at" ] } }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "draftedAt": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "nullable": true }, "followUpAt": { "type": "string", "nullable": true }, "followUpDue": { "type": "boolean" }, "sendOnXUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "status", "person", "notes", "messages", "draftText", "draftReason", "draftedAt", "lastMessageAt", "followUpAt", "followUpDue", "sendOnXUrl", "createdAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_dms_conversationId", "summary": "Delete a DM conversation", "description": "Stops tracking a conversation and deletes what was logged. Nothing changes on X.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stops tracking a conversation and deletes what was logged. Nothing changes on X.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x" ] }, "status": { "type": "string", "enum": [ "your_turn", "waiting", "closed" ] }, "person": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "profileUrl": { "type": "string" } }, "required": [ "handle", "name", "bio", "followers", "profileUrl" ] }, "notes": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" }, "at": { "type": "string" } }, "required": [ "id", "from", "text", "at" ] } }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "draftedAt": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "nullable": true }, "followUpAt": { "type": "string", "nullable": true }, "followUpDue": { "type": "boolean" }, "sendOnXUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "status", "person", "notes", "messages", "draftText", "draftReason", "draftedAt", "lastMessageAt", "followUpAt", "followUpDue", "sendOnXUrl", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/dms": { "get": { "operationId": "get_v1_orgs_orgId_dms", "summary": "List DM conversations", "description": "Lists the X direct-message conversations the user is tracking, with the drafted next message. Conversations where it's the user's turn come first, then ones where a follow-up is due.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "your_turn", "waiting", "follow_up_due", "closed", "all" ] } } ], "responses": { "200": { "description": "Lists the X direct-message conversations the user is tracking, with the drafted next message. Conversations where it's the user's turn come first, then ones where a follow-up is due.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x" ] }, "status": { "type": "string", "enum": [ "your_turn", "waiting", "closed" ] }, "person": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "profileUrl": { "type": "string" } }, "required": [ "handle", "name", "bio", "followers", "profileUrl" ] }, "notes": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" }, "at": { "type": "string" } }, "required": [ "id", "from", "text", "at" ] } }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "draftedAt": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "nullable": true }, "followUpAt": { "type": "string", "nullable": true }, "followUpDue": { "type": "boolean" }, "sendOnXUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "status", "person", "notes", "messages", "draftText", "draftReason", "draftedAt", "lastMessageAt", "followUpAt", "followUpDue", "sendOnXUrl", "createdAt" ] } } }, "required": [ "items" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_dms", "summary": "Add a DM conversation", "description": "Starts tracking a direct-message conversation with someone on X, optionally with the messages so far, and drafts the next message in the user's voice. Adding someone already tracked carries on their conversation. Sends nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": {}, "messages": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" } }, "required": [ "from", "text" ] } }, "notes": { "type": "string" }, "draft": { "type": "boolean" }, "guidance": { "type": "string" } }, "required": [ "handle" ] } } } }, "responses": { "201": { "description": "Starts tracking a direct-message conversation with someone on X, optionally with the messages so far, and drafts the next message in the user's voice. Adding someone already tracked carries on their conversation. Sends nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x" ] }, "status": { "type": "string", "enum": [ "your_turn", "waiting", "closed" ] }, "person": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "profileUrl": { "type": "string" } }, "required": [ "handle", "name", "bio", "followers", "profileUrl" ] }, "notes": { "type": "string", "nullable": true }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "enum": [ "them", "me" ] }, "text": { "type": "string" }, "at": { "type": "string" } }, "required": [ "id", "from", "text", "at" ] } }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "draftedAt": { "type": "string", "nullable": true }, "lastMessageAt": { "type": "string", "nullable": true }, "followUpAt": { "type": "string", "nullable": true }, "followUpDue": { "type": "boolean" }, "sendOnXUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "status", "person", "notes", "messages", "draftText", "draftReason", "draftedAt", "lastMessageAt", "followUpAt", "followUpDue", "sendOnXUrl", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/{itemId}/draft": { "post": { "operationId": "post_v1_orgs_orgId_engagement_itemId_draft", "summary": "Redraft a reply", "description": "Writes a new reply to an inbox item in the brand voice and the way the user writes in their own recent X posts, optionally steered by guidance. Posts nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "guidance": { "type": "string" } } } } } }, "responses": { "200": { "description": "Writes a new reply to an inbox item in the brand voice and the way the user writes in their own recent X posts, optionally steered by guidance. Posts nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "reddit" ] }, "kind": { "type": "string", "enum": [ "mention", "community" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "sending", "sent", "dismissed", "failed" ] }, "externalPostId": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true } }, "required": [ "handle", "name", "followers" ] }, "text": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "likeCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "inReplyToText": { "type": "string", "nullable": true }, "matchedBy": { "type": "string", "nullable": true }, "feedId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "community": { "type": "string", "nullable": true }, "relevance": { "type": "integer", "nullable": true }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "canSendFromApp": { "type": "boolean" }, "replyOnXUrl": { "type": "string" }, "sentUrl": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "kind", "status", "externalPostId", "url", "author", "text", "postedAt", "likeCount", "replyCount", "inReplyToText", "matchedBy", "feedId", "title", "community", "relevance", "draftText", "draftReason", "canSendFromApp", "replyOnXUrl", "sentUrl", "sentAt", "lastError", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/{itemId}": { "patch": { "operationId": "patch_v1_orgs_orgId_engagement_itemId", "summary": "Edit or dismiss a reply", "description": "Edits a drafted reply, dismisses the item, brings it back, or records a reply posted on X by hand. Never posts anything.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draftText": { "type": "string" }, "status": { "type": "string", "enum": [ "drafted", "dismissed", "sent" ] } } } } } }, "responses": { "200": { "description": "Edits a drafted reply, dismisses the item, brings it back, or records a reply posted on X by hand. Never posts anything.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "reddit" ] }, "kind": { "type": "string", "enum": [ "mention", "community" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "sending", "sent", "dismissed", "failed" ] }, "externalPostId": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true } }, "required": [ "handle", "name", "followers" ] }, "text": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "likeCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "inReplyToText": { "type": "string", "nullable": true }, "matchedBy": { "type": "string", "nullable": true }, "feedId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "community": { "type": "string", "nullable": true }, "relevance": { "type": "integer", "nullable": true }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "canSendFromApp": { "type": "boolean" }, "replyOnXUrl": { "type": "string" }, "sentUrl": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "kind", "status", "externalPostId", "url", "author", "text", "postedAt", "likeCount", "replyCount", "inReplyToText", "matchedBy", "feedId", "title", "community", "relevance", "draftText", "draftReason", "canSendFromApp", "replyOnXUrl", "sentUrl", "sentAt", "lastError", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/{itemId}/send": { "post": { "operationId": "post_v1_orgs_orgId_engagement_itemId_send", "summary": "Send an approved reply", "description": "Posts the approved reply to a mention on X, or as a comment on a Reddit thread from the connected Reddit account. Sending is the approval, so the exact text is required. X community posts can't be replied to through X's API; post those on X with the item's replyOnXUrl.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Posts the approved reply to a mention on X, or as a comment on a Reddit thread from the connected Reddit account. Sending is the approval, so the exact text is required. X community posts can't be replied to through X's API; post those on X with the item's replyOnXUrl.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "reddit" ] }, "kind": { "type": "string", "enum": [ "mention", "community" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "sending", "sent", "dismissed", "failed" ] }, "externalPostId": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true } }, "required": [ "handle", "name", "followers" ] }, "text": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "likeCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "inReplyToText": { "type": "string", "nullable": true }, "matchedBy": { "type": "string", "nullable": true }, "feedId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "community": { "type": "string", "nullable": true }, "relevance": { "type": "integer", "nullable": true }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "canSendFromApp": { "type": "boolean" }, "replyOnXUrl": { "type": "string" }, "sentUrl": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "kind", "status", "externalPostId", "url", "author", "text", "postedAt", "likeCount", "replyCount", "inReplyToText", "matchedBy", "feedId", "title", "community", "relevance", "draftText", "draftReason", "canSendFromApp", "replyOnXUrl", "sentUrl", "sentAt", "lastError", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement": { "get": { "operationId": "get_v1_orgs_orgId_engagement", "summary": "List the reply inbox", "description": "Lists replies, mentions and community posts on X, and Reddit threads found by listening, with their drafted replies, newest first. Open items (the default) are those still waiting on a decision.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "sent", "dismissed", "all" ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mention", "community", "all" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "x", "reddit", "all" ] } }, { "name": "feedId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lists replies, mentions and community posts on X, and Reddit threads found by listening, with their drafted replies, newest first. Open items (the default) are those still waiting on a decision.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "reddit" ] }, "kind": { "type": "string", "enum": [ "mention", "community" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "sending", "sent", "dismissed", "failed" ] }, "externalPostId": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true } }, "required": [ "handle", "name", "followers" ] }, "text": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "likeCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "inReplyToText": { "type": "string", "nullable": true }, "matchedBy": { "type": "string", "nullable": true }, "feedId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "community": { "type": "string", "nullable": true }, "relevance": { "type": "integer", "nullable": true }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "canSendFromApp": { "type": "boolean" }, "replyOnXUrl": { "type": "string" }, "sentUrl": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "kind", "status", "externalPostId", "url", "author", "text", "postedAt", "likeCount", "replyCount", "inReplyToText", "matchedBy", "feedId", "title", "community", "relevance", "draftText", "draftReason", "canSendFromApp", "replyOnXUrl", "sentUrl", "sentAt", "lastError", "createdAt" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/reddit-suggestions": { "post": { "operationId": "post_v1_orgs_orgId_engagement_reddit_suggestions", "summary": "Suggest Reddit listening setup", "description": "Suggests pain-point phrases and subreddits to listen to on Reddit, from the brand profile and strategy. Saves nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Suggests pain-point phrases and subreddits to listen to on Reddit, from the brand profile and strategy. Saves nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "redditKeywords": { "type": "array", "items": { "type": "string" } }, "subreddits": { "type": "array", "items": { "type": "string" } } }, "required": [ "redditKeywords", "subreddits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/refresh": { "post": { "operationId": "post_v1_orgs_orgId_engagement_refresh", "summary": "Check X and Reddit for new replies", "description": "Pulls new replies, mentions and community posts from X, and Reddit threads about the workspace's pain points, into the reply inbox and drafts a reply to each. Posts nothing.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Pulls new replies, mentions and community posts from X, and Reddit threads about the workspace's pain points, into the reply inbox and drafts a reply to each. Posts nothing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" }, "drafted": { "type": "integer" }, "mentionsFound": { "type": "integer" }, "communityFound": { "type": "integer" }, "redditFound": { "type": "integer" }, "feedsFound": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "reddit" ] }, "kind": { "type": "string", "enum": [ "mention", "community" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "sending", "sent", "dismissed", "failed" ] }, "externalPostId": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true } }, "required": [ "handle", "name", "followers" ] }, "text": { "type": "string" }, "postedAt": { "type": "string", "nullable": true }, "likeCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "inReplyToText": { "type": "string", "nullable": true }, "matchedBy": { "type": "string", "nullable": true }, "feedId": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "community": { "type": "string", "nullable": true }, "relevance": { "type": "integer", "nullable": true }, "draftText": { "type": "string", "nullable": true }, "draftReason": { "type": "string", "nullable": true }, "canSendFromApp": { "type": "boolean" }, "replyOnXUrl": { "type": "string" }, "sentUrl": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "kind", "status", "externalPostId", "url", "author", "text", "postedAt", "likeCount", "replyCount", "inReplyToText", "matchedBy", "feedId", "title", "community", "relevance", "draftText", "draftReason", "canSendFromApp", "replyOnXUrl", "sentUrl", "sentAt", "lastError", "createdAt" ] } } }, "required": [ "added", "drafted", "mentionsFound", "communityFound", "redditFound", "feedsFound", "warnings", "items" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/settings": { "get": { "operationId": "get_v1_orgs_orgId_engagement_settings", "summary": "Get reply inbox settings", "description": "The X accounts and keywords the reply inbox watches, its saved Engage feeds, the Reddit pain-point phrases and subreddits it listens to, and whether it checks automatically.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The X accounts and keywords the reply inbox watches, its saved Engage feeds, the Reddit pain-point phrases and subreddits it listens to, and whether it checks automatically.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "watchHandles": { "type": "array", "items": {} }, "keywords": { "type": "array", "items": { "type": "string" } }, "autoRefresh": { "type": "boolean" }, "redditKeywords": { "type": "array", "items": { "type": "string" } }, "subreddits": { "type": "array", "items": {} }, "redditExcludeTerms": { "type": "array", "items": { "type": "string" } }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "keywords", "list", "people" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "listId": { "type": "string", "nullable": true }, "handles": { "type": "array", "items": { "type": "string" } }, "minFollowers": { "type": "number", "nullable": true }, "maxFollowers": { "type": "number", "nullable": true }, "enabled": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "nullable": true } }, "required": [ "id", "name", "source", "keywords", "listId", "handles", "minFollowers", "maxFollowers", "enabled", "lastCheckedAt" ] } }, "lastRefreshedAt": { "type": "string", "nullable": true } }, "required": [ "watchHandles", "keywords", "autoRefresh", "redditKeywords", "subreddits", "redditExcludeTerms", "feeds", "lastRefreshedAt" ] } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "put_v1_orgs_orgId_engagement_settings", "summary": "Update reply inbox settings", "description": "Sets the X accounts (up to 10) and keywords (up to 5) to watch for community posts, up to 5 Engage feeds, the Reddit pain-point phrases (up to 8) and subreddits (up to 10) to listen to, and whether to check automatically.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "watchHandles": { "type": "array", "items": {} }, "keywords": { "type": "array", "items": { "type": "string" } }, "autoRefresh": { "type": "boolean" }, "redditKeywords": { "type": "array", "items": { "type": "string" } }, "subreddits": { "type": "array", "items": {} }, "redditExcludeTerms": { "type": "array", "items": { "type": "string" } }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "keywords", "list", "people" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "listId": { "nullable": true }, "handles": { "type": "array", "items": {} }, "minFollowers": { "type": "integer", "nullable": true }, "maxFollowers": { "type": "integer", "nullable": true }, "enabled": { "type": "boolean" } }, "required": [ "name", "source" ] } } } } } } }, "responses": { "200": { "description": "Sets the X accounts (up to 10) and keywords (up to 5) to watch for community posts, up to 5 Engage feeds, the Reddit pain-point phrases (up to 8) and subreddits (up to 10) to listen to, and whether to check automatically.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "watchHandles": { "type": "array", "items": {} }, "keywords": { "type": "array", "items": { "type": "string" } }, "autoRefresh": { "type": "boolean" }, "redditKeywords": { "type": "array", "items": { "type": "string" } }, "subreddits": { "type": "array", "items": {} }, "redditExcludeTerms": { "type": "array", "items": { "type": "string" } }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "keywords", "list", "people" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "listId": { "type": "string", "nullable": true }, "handles": { "type": "array", "items": { "type": "string" } }, "minFollowers": { "type": "number", "nullable": true }, "maxFollowers": { "type": "number", "nullable": true }, "enabled": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "nullable": true } }, "required": [ "id", "name", "source", "keywords", "listId", "handles", "minFollowers", "maxFollowers", "enabled", "lastCheckedAt" ] } }, "lastRefreshedAt": { "type": "string", "nullable": true } }, "required": [ "watchHandles", "keywords", "autoRefresh", "redditKeywords", "subreddits", "redditExcludeTerms", "feeds", "lastRefreshedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/engagement/x-account-suggestions": { "post": { "operationId": "post_v1_orgs_orgId_engagement_x_account_suggestions", "summary": "Find X accounts to engage with", "description": "Suggests up to 15 X accounts the workspace's audience follows, checked against X for existence and size. Runs at most once a week; within the week it returns the saved suggestions at no cost. Saves no feed.", "tags": [ "engagement" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Suggests up to 15 X accounts the workspace's audience follows, checked against X for existence and size. Runs at most once a week; within the week it returns the saved suggestions at no cost. Saves no feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "handle": { "type": "string" }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "bio": { "type": "string", "nullable": true }, "reason": { "type": "string" } }, "required": [ "handle", "name", "followers", "bio", "reason" ] } }, "generatedAt": { "type": "string" }, "cached": { "type": "boolean" }, "nextRefreshAt": { "type": "string" } }, "required": [ "accounts", "generatedAt", "cached", "nextRefreshAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/feedback": { "post": { "operationId": "post_v1_orgs_orgId_feedback", "summary": "Send feedback to the AdVentur.ai team", "description": "Emails a message from the signed-in user to the AdVentur.ai team, with their workspace, plan, page and app version so it can be followed up.", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "page": { "type": "string" }, "appVersion": { "type": "string" } }, "required": [ "message" ] } } } }, "responses": { "200": { "description": "Emails a message from the signed-in user to the AdVentur.ai team, with their workspace, plan, page and app version so it can be followed up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "const": true, "type": "boolean" } }, "required": [ "sent" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/home": { "get": { "operationId": "get_v1_orgs_orgId_home", "summary": "Get AI employee home summary", "description": "Composable HOME-01 operating surface: daily brief, needs attention, approval queue, schedule coverage, wins, activity, and chat suggestions.", "tags": [ "home" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Composable HOME-01 operating surface: daily brief, needs attention, approval queue, schedule coverage, wins, activity, and chat suggestions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "generatedAt": { "type": "string" }, "activated": { "type": "boolean" }, "onboardingComplete": { "type": "boolean" }, "alphaActivated": { "type": "boolean" }, "brandConfirmed": { "type": "boolean" }, "timezone": { "type": "string" }, "autonomyMode": { "type": "string", "enum": [ "approval", "trusted", "autopilot" ] }, "brief": { "type": "object", "properties": { "headline": { "type": "string" }, "body": { "type": "string" } }, "required": [ "headline", "body" ] }, "attention": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval_queue", "schedule_gap", "account_reconnect", "strategy_review", "publish_failure", "billing", "onboarding", "brand_confirm" ] }, "severity": { "type": "string", "enum": [ "action", "warning", "info" ] }, "title": { "type": "string" }, "detail": { "type": "string" }, "ctaLabel": { "type": "string" }, "ctaHref": { "type": "string" } }, "required": [ "id", "kind", "severity", "title", "detail", "ctaLabel", "ctaHref" ] } }, "approvalQueue": { "type": "object", "properties": { "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "contentText": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "postId", "groupId", "platform", "contentText", "topic", "updatedAt" ] } }, "previewLimit": { "type": "integer" } }, "required": [ "count", "items", "previewLimit" ] }, "schedule": { "type": "object", "properties": { "upcomingCount": { "type": "integer" }, "overallStatus": { "type": "string", "enum": [ "covered", "needs_attention" ] }, "summary": { "type": "string" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "status": { "type": "string", "enum": [ "covered", "gap", "clustered", "waiting" ] }, "scheduledCount": { "type": "integer" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "platform", "status", "scheduledCount", "notes" ] } }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "contentText": { "type": "string" }, "scheduledForUtc": { "type": "string", "nullable": true } }, "required": [ "postId", "platform", "contentText", "scheduledForUtc" ] } } }, "required": [ "upcomingCount", "overallStatus", "summary", "channels", "upcoming" ] }, "wins": { "type": "object", "properties": { "postsPublished": { "type": "integer" }, "impressions": { "type": "number", "nullable": true }, "engagements": { "type": "number" }, "engagementRate": { "type": "number", "nullable": true }, "consistencyLabel": { "type": "string", "enum": [ "strong", "steady", "sparse", "none" ] }, "topPostSnippet": { "type": "string", "nullable": true }, "href": { "type": "string" } }, "required": [ "postsPublished", "impressions", "engagements", "engagementRate", "consistencyLabel", "topPostSnippet", "href" ] }, "activeWork": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "href": { "type": "string", "nullable": true } }, "required": [ "id", "title", "detail", "href" ] } }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventName": { "type": "string" }, "occurredAt": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "href": { "type": "string", "nullable": true } }, "required": [ "id", "eventName", "occurredAt", "title", "detail", "href" ] } } }, "required": [ "generatedAt", "activated", "onboardingComplete", "alphaActivated", "brandConfirmed", "timezone", "autonomyMode", "brief", "attention", "approvalQueue", "schedule", "wins", "activeWork", "activity" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/{itemId}/analyze": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_itemId_analyze", "summary": "Analyze inspiration item", "description": "Run (or re-run) AI analysis and workspace opportunity ranking (relevance + why this matters).", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run (or re-run) AI analysis and workspace opportunity ranking (relevance + why this matters).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/{itemId}/feedback": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_itemId_feedback", "summary": "Record inspiration opportunity feedback", "description": "Save, hide, dismiss, or reopen an inspiration opportunity to improve future ranking.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "save", "hide", "dismiss", "reopen" ] }, "reason": { "type": "string" } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Save, hide, dismiss, or reopen an inspiration opportunity to improve future ranking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/{itemId}/generate": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_itemId_generate", "summary": "Generate content from inspiration", "description": "Create original LinkedIn/X/thread/article drafts inspired by a library opportunity while following brand voice, strategy, and avoiding plagiarism.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destinations": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] } }, "tone": { "type": "string" }, "objective": { "type": "string" }, "additionalGuidance": { "type": "string" } }, "required": [ "destinations" ] } } } }, "responses": { "200": { "description": "Create original LinkedIn/X/thread/article drafts inspired by a library opportunity while following brand voice, strategy, and avoiding plagiarism.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "provider": { "type": "string" }, "providerModel": { "type": "string" }, "promptVersion": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" }, "pendingApprovalGroupId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "drafts", "provider", "providerModel", "promptVersion", "creditsUsed", "remainingCredits", "pendingApprovalGroupId" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/{itemId}": { "get": { "operationId": "get_v1_orgs_orgId_inspiration_itemId", "summary": "Get inspiration item", "description": "Get a single inspiration library item.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get a single inspiration library item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_inspiration_itemId", "summary": "Update inspiration item", "description": "Update notes, tags, or content on an inspiration item.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "contentText": { "type": "string" }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } } } } } } }, "responses": { "200": { "description": "Update notes, tags, or content on an inspiration item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_inspiration_itemId", "summary": "Delete inspiration item", "description": "Remove an item from the inspiration library.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Remove an item from the inspiration library.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/algorithm-hints": { "get": { "operationId": "get_v1_orgs_orgId_inspiration_algorithm_hints", "summary": "Get platform algorithm hints", "description": "What each social platform's feed currently rewards and punishes, with the evidence, a confidence level and cited sources, so posts can be shaped for reach.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] } } ], "responses": { "200": { "description": "What each social platform's feed currently rewards and punishes, with the evidence, a confidence level and cited sources, so posts can be shaped for reach.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reviewedAt": { "type": "string" }, "caveat": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "summary": { "type": "string" }, "hints": {}, "sources": {} }, "required": [ "platform", "summary", "hints", "sources" ] } } }, "required": [ "reviewedAt", "caveat", "platforms" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/formats": { "get": { "operationId": "get_v1_orgs_orgId_inspiration_formats", "summary": "List viral post formats", "description": "Proven X and LinkedIn post formats with the structure, a fill-in template and an example of each, so a brand can borrow the shape of posts that spread.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "x", "linkedin" ] } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hot_take", "list", "story", "news", "engagement", "data", "how_to" ] } } ], "responses": { "200": { "description": "Proven X and LinkedIn post formats with the structure, a fill-in template and an example of each, so a brand can borrow the shape of posts that spread.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "hot_take", "list", "story", "news", "engagement", "data", "how_to" ] }, "summary": { "type": "string" }, "whyItWorks": { "type": "string" }, "structure": {}, "template": { "type": "string" }, "example": { "type": "string" }, "bestFor": {} }, "required": [ "id", "platform", "name", "category", "summary", "whyItWorks", "structure", "template", "example", "bestFor" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/import/account": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_import_account", "summary": "Import inspiration from connected account", "description": "Import the authenticated user's recent X or LinkedIn posts into the inspiration library for AI analysis.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "socialAccountId": { "type": "string", "format": "uuid" }, "limit": { "type": "integer" }, "analyze": { "type": "boolean" } }, "required": [ "platform" ] } } } }, "responses": { "200": { "description": "Import the authenticated user's recent X or LinkedIn posts into the inspiration library for AI analysis.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "imported": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "skipped": { "type": "number" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "imported", "skipped", "errors" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/import/external": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_import_external", "summary": "Import inspiration from external client", "description": "Accepts structured inspiration payloads from browser extensions or other external clients.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceExternalId": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string" }, "authorHandle": { "type": "string" }, "authorProfileUrl": { "type": "string", "format": "uri" }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } } }, "publishedAt": { "type": "string" }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } } }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "client": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "analyze": { "type": "boolean" } }, "required": [ "platform", "contentText" ] } } } }, "responses": { "200": { "description": "Accepts structured inspiration payloads from browser extensions or other external clients.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/import": { "post": { "operationId": "post_v1_orgs_orgId_inspiration_import", "summary": "Manually import inspiration", "description": "Import inspiration by pasting a LinkedIn/X URL and/or raw post text.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "contentText": { "type": "string" }, "authorName": { "type": "string" }, "authorHandle": { "type": "string" }, "authorProfileUrl": { "type": "string", "format": "uri" }, "publishedAt": { "type": "string" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } } }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } } }, "analyze": { "type": "boolean" } }, "required": [ "platform" ] } } } }, "responses": { "200": { "description": "Import inspiration by pasting a LinkedIn/X URL and/or raw post text.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration": { "get": { "operationId": "get_v1_orgs_orgId_inspiration", "summary": "List inspiration library items", "description": "Returns a unified inspiration library across platforms (X, LinkedIn) with optional filters.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "x", "linkedin" ] } }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "hook", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "audience", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "creator", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "analysisStatus", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] } }, { "name": "opportunityStatus", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] } }, { "name": "includeHidden", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "recent" ] } }, { "name": "savedFrom", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "savedTo", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "verbose", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Returns a unified inspiration library across platforms (X, LinkedIn) with optional filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceType": { "type": "string", "enum": [ "own_account", "manual_url", "manual_text", "extension" ] }, "sourceExternalId": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "authorHandle": { "type": "string", "nullable": true }, "authorProfileUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document", "link", "other" ] }, "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "mimeType": { "type": "string" } } } } }, "nullable": true }, "publishedAt": { "type": "string", "nullable": true }, "engagement": { "type": "object", "properties": { "likes": { "type": "integer", "nullable": true }, "comments": { "type": "integer", "nullable": true }, "shares": { "type": "integer", "nullable": true }, "impressions": { "type": "integer", "nullable": true }, "bookmarks": { "type": "integer", "nullable": true }, "quotes": { "type": "integer", "nullable": true }, "raw": { "type": "object", "additionalProperties": {}, "nullable": true } }, "nullable": true }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "analysisError": { "type": "string", "nullable": true }, "analysis": { "type": "object", "properties": { "topic": { "type": "string" }, "hook": { "type": "string" }, "format": { "type": "string" }, "tone": { "type": "string" }, "audience": { "type": "string" }, "cta": { "type": "string" }, "writingFramework": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "qualityScore": { "type": "number" } }, "required": [ "topic", "hook", "format", "tone", "audience", "cta", "writingFramework", "keywords", "qualityScore" ], "nullable": true }, "analysisProvider": { "type": "string", "nullable": true }, "analysisModel": { "type": "string", "nullable": true }, "analysisPromptVersion": { "type": "string", "nullable": true }, "analyzedAt": { "type": "string", "nullable": true }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "generatedAt": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "createdBy": { "type": "string", "format": "uuid", "nullable": true }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "feedbackReason": { "type": "string", "nullable": true }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "interpretation": { "type": "object", "properties": { "relevanceScore": { "type": "number" }, "whyItMatters": { "type": "string" }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ] }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } } }, "required": [ "relevanceScore", "whyItMatters", "scoreBreakdown" ], "nullable": true }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "platform", "sourceType", "sourceExternalId", "sourceUrl", "authorName", "authorHandle", "authorProfileUrl", "contentText", "media", "publishedAt", "engagement", "analysisStatus", "analysisError", "analysis", "analysisProvider", "analysisModel", "analysisPromptVersion", "analyzedAt", "generatedAt", "notes", "tags", "socialAccountId", "createdBy", "feedbackReason", "relevanceScore", "whyItMatters", "interpretation", "strategyId", "strategyVersion", "createdAt", "updatedAt" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "sourceUrl": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "contentExcerpt": { "type": "string" }, "contentTruncated": { "type": "boolean" }, "analysisStatus": { "type": "string", "enum": [ "pending", "processing", "ready", "failed", "skipped" ] }, "topic": { "type": "string", "nullable": true }, "hook": { "type": "string", "nullable": true }, "keywords": { "type": "array", "items": { "type": "string" } }, "opportunityStatus": { "type": "string", "enum": [ "open", "saved", "hidden", "dismissed", "acted_on" ] }, "relevanceScore": { "type": "number", "nullable": true }, "whyItMatters": { "type": "string", "nullable": true }, "scoreBreakdown": { "type": "object", "properties": { "strategyFit": { "type": "number" }, "audienceFit": { "type": "number" }, "quality": { "type": "number" }, "freshness": { "type": "number" }, "engagement": { "type": "number" } }, "required": [ "strategyFit", "audienceFit", "quality", "freshness", "engagement" ], "nullable": true }, "matchedPillars": { "type": "array", "items": { "type": "string" } }, "matchedPriorities": { "type": "array", "items": { "type": "string" } }, "strategyNotes": { "type": "array", "items": { "type": "string" } }, "generatedDrafts": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "enum": [ "x", "linkedin", "thread", "article" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "destination", "styleKey", "text" ] } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" } }, "required": [ "id", "platform", "sourceUrl", "authorName", "contentExcerpt", "contentTruncated", "analysisStatus", "topic", "hook", "keywords", "opportunityStatus", "relevanceScore", "whyItMatters", "scoreBreakdown", "matchedPillars", "matchedPriorities", "strategyNotes", "generatedDrafts", "tags", "createdAt" ] } ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/news": { "get": { "operationId": "get_v1_orgs_orgId_inspiration_news", "summary": "Get recent news in the workspace's niche", "description": "Recent web news for the topics the workspace follows (its research focus, brand topics and expertise). Topics are shared across workspaces and refreshed hourly, so this is served from the research cache and spends no credits.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recent web news for the topics the workspace follows (its research focus, brand topics and expertise). Topics are shared across workspaces and refreshed hourly, so this is served from the research cache and spends no credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "grounded": { "type": "boolean" }, "reason": { "type": "string", "nullable": true }, "topics": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "publishedAt": { "type": "string", "nullable": true } }, "required": [ "title", "url", "snippet", "publishedAt" ] } } }, "required": [ "slug", "label", "articles" ] } } }, "required": [ "grounded", "reason", "topics" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/inspiration/trends": { "get": { "operationId": "get_v1_orgs_orgId_inspiration_trends", "summary": "Get the latest trending topics report", "description": "Returns the most recent trending-topics report for the workspace, or null when none has been run.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns the most recent trending-topics report for the workspace, or null when none has been run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "focus": { "type": "string", "nullable": true }, "grounded": { "type": "boolean" }, "groundingReason": { "type": "string", "nullable": true }, "xSearch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "no_posts", "failed", "unavailable" ] }, "postsFound": { "type": "integer" }, "sourcesCited": { "type": "integer" }, "message": { "type": "string", "nullable": true } }, "required": [ "status", "postsFound", "sourcesCited", "message" ], "nullable": true }, "searchQueries": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "whyNow": { "type": "string" }, "momentum": { "type": "string", "enum": [ "breaking", "rising", "evergreen" ] }, "hotTake": { "type": "string" }, "brandAngle": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "publishedAt": { "type": "string", "nullable": true }, "platform": { "type": "string", "enum": [ "web", "x" ] } }, "required": [ "title", "url", "publishedAt" ] } }, "postIdeas": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "formatId": { "type": "string" }, "formatName": { "type": "string" }, "text": { "type": "string" }, "template": { "type": "boolean" } }, "required": [ "platform", "formatId", "formatName", "text" ] } } }, "required": [ "id", "title", "summary", "whyNow", "momentum", "hotTake", "brandAngle", "sources", "postIdeas" ] } }, "generatedAt": { "type": "string" } }, "required": [ "id", "focus", "grounded", "searchQueries", "topics", "generatedAt" ], "nullable": true } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_inspiration_trends", "summary": "Find trending topics and news to post about", "description": "Searches the web and recent X posts for news and debates in the brand's niche (or a given focus), then suggests hot takes and X / LinkedIn posts in proven viral formats. Counts toward the workspace's monthly AI usage allowance (including X reads), and saves the report.", "tags": [ "inspiration" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "focus": { "type": "string" }, "maxTopics": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin" ] } } } } } } }, "responses": { "200": { "description": "Searches the web and recent X posts for news and debates in the brand's niche (or a given focus), then suggests hot takes and X / LinkedIn posts in proven viral formats. Counts toward the workspace's monthly AI usage allowance (including X reads), and saves the report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "focus": { "type": "string", "nullable": true }, "grounded": { "type": "boolean" }, "groundingReason": { "type": "string", "nullable": true }, "xSearch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "no_posts", "failed", "unavailable" ] }, "postsFound": { "type": "integer" }, "sourcesCited": { "type": "integer" }, "message": { "type": "string", "nullable": true } }, "required": [ "status", "postsFound", "sourcesCited", "message" ], "nullable": true }, "searchQueries": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "whyNow": { "type": "string" }, "momentum": { "type": "string", "enum": [ "breaking", "rising", "evergreen" ] }, "hotTake": { "type": "string" }, "brandAngle": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "publishedAt": { "type": "string", "nullable": true }, "platform": { "type": "string", "enum": [ "web", "x" ] } }, "required": [ "title", "url", "publishedAt" ] } }, "postIdeas": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin" ] }, "formatId": { "type": "string" }, "formatName": { "type": "string" }, "text": { "type": "string" }, "template": { "type": "boolean" } }, "required": [ "platform", "formatId", "formatName", "text" ] } } }, "required": [ "id", "title", "summary", "whyNow", "momentum", "hotTake", "brandAngle", "sources", "postIdeas" ] } }, "generatedAt": { "type": "string" } }, "required": [ "id", "focus", "grounded", "searchQueries", "topics", "generatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/invitations/{invitationId}": { "delete": { "operationId": "delete_v1_orgs_orgId_invitations_invitationId", "summary": "DELETE /v1/orgs/{orgId}/invitations/{invitationId}", "description": "DELETE /v1/orgs/{orgId}/invitations/{invitationId}", "tags": [ "invitations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/invitations/{invitationId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/invitations": { "get": { "operationId": "get_v1_orgs_orgId_invitations", "summary": "GET /v1/orgs/{orgId}/invitations", "description": "GET /v1/orgs/{orgId}/invitations", "tags": [ "invitations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "expiresAt", "email", "status", "roleKey" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string" }, "email": { "type": "string" }, "roleKey": { "type": "string" }, "createdAtFrom": { "type": "string" }, "createdAtTo": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "eq", "in" ] }, "email": { "type": "string", "enum": [ "eq", "contains" ] }, "roleKey": { "type": "string", "enum": [ "eq", "in" ] }, "createdAtFrom": { "type": "string", "enum": [ "gte" ] }, "createdAtTo": { "type": "string", "enum": [ "lte" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "roleKey": { "type": "string" }, "roleName": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "roleKey", "roleName", "status", "expiresAt", "createdAt" ] } } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_invitations", "summary": "POST /v1/orgs/{orgId}/invitations", "description": "POST /v1/orgs/{orgId}/invitations", "tags": [ "invitations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "roleKey": { "type": "string" } }, "required": [ "email", "roleKey" ] } } } }, "responses": { "201": { "description": "POST /v1/orgs/{orgId}/invitations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "roleKey": { "type": "string" }, "status": { "type": "string" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "email", "roleKey", "status", "expiresAt", "createdAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/launch-kits/{kitId}": { "get": { "operationId": "get_v1_orgs_orgId_launch_kits_kitId", "summary": "Get a launch kit", "description": "The kit's Product Hunt and Show HN copy and its day-by-day plan, with each drafted post's current status.", "tags": [ "launch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kitId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The kit's Product Hunt and Show HN copy and its day-by-day plan, with each drafted post's current status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "pitch": { "type": "string" }, "url": { "type": "string", "nullable": true }, "launchDate": { "type": "string" }, "timezone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ] } }, "productHunt": { "type": "object", "properties": { "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "firstComment": { "type": "string" }, "galleryIdeas": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "tagline", "description", "topics", "firstComment", "galleryIdeas" ], "nullable": true }, "hackerNews": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "nullable": true }, "text": { "type": "string" } }, "required": [ "title", "url", "text" ], "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "integer" }, "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "scheduledForUtc": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "post", "listing", "task" ] }, "channel": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ], "nullable": true }, "title": { "type": "string" }, "detail": { "type": "string" }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "postStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ], "nullable": true }, "postText": { "type": "string", "nullable": true }, "done": { "type": "boolean" } }, "required": [ "id", "day", "date", "time", "scheduledForUtc", "kind", "channel", "title", "detail", "groupId", "platform", "postStatus", "postText", "done" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "productName", "pitch", "url", "launchDate", "timezone", "channels", "productHunt", "hackerNews", "steps", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_launch_kits_kitId", "summary": "Tick off a launch plan step", "description": "Marks one step of the launch plan done, or not done.", "tags": [ "launch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kitId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stepId": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "stepId", "done" ] } } } }, "responses": { "200": { "description": "Marks one step of the launch plan done, or not done.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "pitch": { "type": "string" }, "url": { "type": "string", "nullable": true }, "launchDate": { "type": "string" }, "timezone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ] } }, "productHunt": { "type": "object", "properties": { "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "firstComment": { "type": "string" }, "galleryIdeas": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "tagline", "description", "topics", "firstComment", "galleryIdeas" ], "nullable": true }, "hackerNews": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "nullable": true }, "text": { "type": "string" } }, "required": [ "title", "url", "text" ], "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "integer" }, "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "scheduledForUtc": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "post", "listing", "task" ] }, "channel": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ], "nullable": true }, "title": { "type": "string" }, "detail": { "type": "string" }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "postStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ], "nullable": true }, "postText": { "type": "string", "nullable": true }, "done": { "type": "boolean" } }, "required": [ "id", "day", "date", "time", "scheduledForUtc", "kind", "channel", "title", "detail", "groupId", "platform", "postStatus", "postText", "done" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "productName", "pitch", "url", "launchDate", "timezone", "channels", "productHunt", "hackerNews", "steps", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/launch-kits": { "get": { "operationId": "get_v1_orgs_orgId_launch_kits", "summary": "List launch kits", "description": "Lists the workspace's launch kits, newest first, with plan progress.", "tags": [ "launch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lists the workspace's launch kits, newest first, with plan progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "launchDate": { "type": "string" }, "timezone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ] } }, "createdAt": { "type": "string" }, "stepCount": { "type": "integer" }, "doneCount": { "type": "integer" } }, "required": [ "id", "productName", "launchDate", "timezone", "channels", "createdAt", "stepCount", "doneCount" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_launch_kits", "summary": "Create a launch kit", "description": "Writes a product launch in the brand voice: a Product Hunt listing and Show HN post to paste, launch posts for X, LinkedIn and Reddit drafted into Review as pending approval, and a day-by-day plan. Never schedules or publishes.", "tags": [ "launch" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pitch": { "type": "string" }, "productName": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "launchDate": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ] } }, "subreddits": { "type": "array", "items": {} }, "guidance": { "type": "string" } }, "required": [ "pitch", "launchDate" ] } } } }, "responses": { "201": { "description": "Writes a product launch in the brand voice: a Product Hunt listing and Show HN post to paste, launch posts for X, LinkedIn and Reddit drafted into Review as pending approval, and a day-by-day plan. Never schedules or publishes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "kit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "productName": { "type": "string" }, "pitch": { "type": "string" }, "url": { "type": "string", "nullable": true }, "launchDate": { "type": "string" }, "timezone": { "type": "string" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ] } }, "productHunt": { "type": "object", "properties": { "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "firstComment": { "type": "string" }, "galleryIdeas": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "tagline", "description", "topics", "firstComment", "galleryIdeas" ], "nullable": true }, "hackerNews": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "nullable": true }, "text": { "type": "string" } }, "required": [ "title", "url", "text" ], "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "integer" }, "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "scheduledForUtc": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "post", "listing", "task" ] }, "channel": { "type": "string", "enum": [ "product_hunt", "hacker_news", "x", "linkedin", "reddit" ], "nullable": true }, "title": { "type": "string" }, "detail": { "type": "string" }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "postStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ], "nullable": true }, "postText": { "type": "string", "nullable": true }, "done": { "type": "boolean" } }, "required": [ "id", "day", "date", "time", "scheduledForUtc", "kind", "channel", "title", "detail", "groupId", "platform", "postStatus", "postText", "done" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "productName", "pitch", "url", "launchDate", "timezone", "channels", "productHunt", "hackerNews", "steps", "createdAt", "updatedAt" ] }, "providerModel": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" } }, "required": [ "kit", "providerModel", "creditsUsed", "remainingCredits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/logo": { "get": { "operationId": "get_v1_orgs_orgId_logo", "summary": "GET /v1/orgs/{orgId}/logo", "description": "GET /v1/orgs/{orgId}/logo", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/logo", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "url": { "type": "string" }, "expiresInSeconds": { "type": "number" } }, "required": [ "key", "url", "expiresInSeconds" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_logo", "summary": "POST /v1/orgs/{orgId}/logo", "description": "POST /v1/orgs/{orgId}/logo", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/logo", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "key": { "type": "string" } }, "required": [ "avatarUrl", "key" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_logo", "summary": "DELETE /v1/orgs/{orgId}/logo", "description": "DELETE /v1/orgs/{orgId}/logo", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/logo", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/orgs/{orgId}/logo/upload-url": { "post": { "operationId": "post_v1_orgs_orgId_logo_upload_url", "summary": "POST /v1/orgs/{orgId}/logo/upload-url", "description": "POST /v1/orgs/{orgId}/logo/upload-url", "tags": [ "branding" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string" } }, "required": [ "contentType" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/logo/upload-url", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploadUrl": { "type": "string" }, "key": { "type": "string" }, "assetUrl": { "type": "string" }, "expiresInSeconds": { "type": "number" }, "method": { "const": "PUT", "type": "string" }, "requiredHeaders": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "uploadUrl", "key", "assetUrl", "expiresInSeconds", "method", "requiredHeaders" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/accounts/{accountId}": { "patch": { "operationId": "patch_v1_orgs_orgId_marketing_accounts_accountId", "summary": "PATCH /v1/orgs/{orgId}/marketing/accounts/{accountId}", "description": "Set the profile link shown for a connected account.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileUrl": { "type": "string", "nullable": true } }, "required": [ "profileUrl" ] } } } }, "responses": { "200": { "description": "Set the profile link shown for a connected account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "accountExternalId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "accountHandle": { "type": "string", "nullable": true }, "profileImageUrl": { "type": "string", "format": "uri", "nullable": true }, "accountBio": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenExpiresAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "xPremium": { "type": "boolean", "nullable": true }, "xSubscription": { "type": "string", "enum": [ "none", "basic", "premium", "premium_plus" ], "nullable": true } }, "required": [ "id", "orgId", "platform", "accountExternalId", "accountName", "accountHandle", "status", "scopes", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_marketing_accounts_accountId", "summary": "DELETE /v1/orgs/{orgId}/marketing/accounts/{accountId}", "description": "DELETE /v1/orgs/{orgId}/marketing/accounts/{accountId}", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/marketing/accounts/{accountId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "accountExternalId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "accountHandle": { "type": "string", "nullable": true }, "profileImageUrl": { "type": "string", "format": "uri", "nullable": true }, "accountBio": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenExpiresAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "xPremium": { "type": "boolean", "nullable": true }, "xSubscription": { "type": "string", "enum": [ "none", "basic", "premium", "premium_plus" ], "nullable": true } }, "required": [ "id", "orgId", "platform", "accountExternalId", "accountName", "accountHandle", "status", "scopes", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/accounts/{accountId}/tiktok/creator-info": { "get": { "operationId": "get_v1_orgs_orgId_marketing_accounts_accountId_tiktok_creator_info", "summary": "GET /v1/orgs/{orgId}/marketing/accounts/{accountId}/tiktok/creator-info", "description": "Fetch the connected TikTok creator's current privacy/interaction options for the composer.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fetch the connected TikTok creator's current privacy/interaction options for the composer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creatorAvatarUrl": { "type": "string", "format": "uri", "nullable": true }, "creatorUsername": { "type": "string", "nullable": true }, "creatorNickname": { "type": "string", "nullable": true }, "privacyLevelOptions": { "type": "array", "items": { "type": "string" } }, "commentDisabled": { "type": "boolean" }, "duetDisabled": { "type": "boolean" }, "stitchDisabled": { "type": "boolean" }, "maxVideoPostDurationSec": { "type": "number", "nullable": true }, "directPostEnabled": { "type": "boolean" } }, "required": [ "creatorAvatarUrl", "creatorUsername", "creatorNickname", "privacyLevelOptions", "commentDisabled", "duetDisabled", "stitchDisabled", "maxVideoPostDurationSec", "directPostEnabled" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/accounts/{platform}/oauth/start": { "post": { "operationId": "post_v1_orgs_orgId_marketing_accounts_platform_oauth_start", "summary": "POST /v1/orgs/{orgId}/marketing/accounts/{platform}/oauth/start", "description": "POST /v1/orgs/{orgId}/marketing/accounts/{platform}/oauth/start", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string", "format": "uri" }, "linkedinTarget": { "type": "string", "enum": [ "profile", "page" ] }, "blueskyHandle": { "type": "string" } }, "required": [ "redirectUri" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/accounts/{platform}/oauth/start", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "required": [ "authorizationUrl", "state" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/accounts/bluesky/connect": { "post": { "operationId": "post_v1_orgs_orgId_marketing_accounts_bluesky_connect", "summary": "POST /v1/orgs/{orgId}/marketing/accounts/bluesky/connect", "description": "Connect a Bluesky account with its handle and an app password.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string" }, "appPassword": { "type": "string" } }, "required": [ "handle", "appPassword" ] } } } }, "responses": { "200": { "description": "Connect a Bluesky account with its handle and an app password.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "accountExternalId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "accountHandle": { "type": "string", "nullable": true }, "profileImageUrl": { "type": "string", "format": "uri", "nullable": true }, "accountBio": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenExpiresAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "xPremium": { "type": "boolean", "nullable": true }, "xSubscription": { "type": "string", "enum": [ "none", "basic", "premium", "premium_plus" ], "nullable": true } }, "required": [ "id", "orgId", "platform", "accountExternalId", "accountName", "accountHandle", "status", "scopes", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/accounts": { "get": { "operationId": "get_v1_orgs_orgId_marketing_accounts", "summary": "GET /v1/orgs/{orgId}/marketing/accounts", "description": "GET /v1/orgs/{orgId}/marketing/accounts", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "accountExternalId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "accountHandle": { "type": "string", "nullable": true }, "profileImageUrl": { "type": "string", "format": "uri", "nullable": true }, "accountBio": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenExpiresAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "xPremium": { "type": "boolean", "nullable": true }, "xSubscription": { "type": "string", "enum": [ "none", "basic", "premium", "premium_plus" ], "nullable": true } }, "required": [ "id", "orgId", "platform", "accountExternalId", "accountName", "accountHandle", "status", "scopes", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/analytics/performance": { "get": { "operationId": "get_v1_orgs_orgId_marketing_analytics_performance", "summary": "Get marketing performance summary", "description": "Customer-facing performance analytics: published volume, impressions/engagement, top posts/topics, consistency and simple trends.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "topLimit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Customer-facing performance analytics: published volume, impressions/engagement, top posts/topics, consistency and simple trends.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "generatedAt": { "type": "string" }, "summary": { "type": "object", "properties": { "postsPublished": { "type": "integer" }, "postsScheduledUpcoming": { "type": "integer" }, "impressions": { "type": "number", "nullable": true }, "engagements": { "type": "number" }, "engagementRate": { "type": "number", "nullable": true }, "publishingActiveDays": { "type": "integer" }, "consistencyLabel": { "type": "string", "enum": [ "strong", "steady", "sparse", "none" ] } }, "required": [ "postsPublished", "postsScheduledUpcoming", "impressions", "engagements", "engagementRate", "publishingActiveDays", "consistencyLabel" ] }, "previousWindow": { "type": "object", "properties": { "postsPublished": { "type": "integer" }, "impressions": { "type": "number", "nullable": true }, "engagements": { "type": "number" } }, "required": [ "postsPublished", "impressions", "engagements" ] }, "trends": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "postsPublished": { "type": "integer" }, "impressions": { "type": "number", "nullable": true }, "engagements": { "type": "number" } }, "required": [ "date", "postsPublished", "impressions", "engagements" ] } }, "topPosts": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ], "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "publishedAt": { "type": "string", "nullable": true }, "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number", "nullable": true }, "impressions": { "type": "number", "nullable": true }, "engagementScore": { "type": "number" }, "topic": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true } }, "required": [ "postId", "platform", "publishedExternalId", "publishedUrl", "contentText", "publishedAt", "likes", "reposts", "replies", "quotes", "bookmarks", "impressions", "engagementScore", "topic", "contentType" ] } }, "topTopics": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "postsPublished": { "type": "integer" }, "engagements": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "topic", "postsPublished", "engagements", "impressions" ] } }, "topContentTypes": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string" }, "postsPublished": { "type": "integer" }, "engagements": { "type": "number" } }, "required": [ "contentType", "postsPublished", "engagements" ] } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "postsPublished": { "type": "integer" }, "impressions": { "type": "number", "nullable": true }, "engagements": { "type": "number" } }, "required": [ "platform", "postsPublished", "impressions", "engagements" ] } }, "audience": { "type": "object", "properties": { "available": { "type": "boolean" }, "note": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "socialAccountId": { "type": "string" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "name": { "type": "string", "nullable": true }, "followers": { "type": "integer", "nullable": true }, "change": { "type": "integer", "nullable": true }, "tracking": { "type": "string", "enum": [ "live", "pending", "needs_permission" ] } }, "required": [ "socialAccountId", "platform", "name", "followers", "change", "tracking" ] } } }, "required": [ "available", "note", "accounts" ] } }, "required": [ "windowDays", "generatedAt", "summary", "previousWindow", "trends", "topPosts", "topTopics", "topContentTypes", "platforms", "audience" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/analytics/refresh": { "post": { "operationId": "post_v1_orgs_orgId_marketing_analytics_refresh", "summary": "POST /v1/orgs/{orgId}/marketing/analytics/refresh", "description": "POST /v1/orgs/{orgId}/marketing/analytics/refresh", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/analytics/refresh", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "processed": { "type": "number" }, "updated": { "type": "number" }, "failed": { "type": "number" }, "skippedFairUse": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "message": { "type": "string" } }, "required": [ "platform", "message" ] } } }, "required": [ "processed", "updated", "failed" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/analytics/top-posts": { "get": { "operationId": "get_v1_orgs_orgId_marketing_analytics_top_posts", "summary": "GET /v1/orgs/{orgId}/marketing/analytics/top-posts", "description": "GET /v1/orgs/{orgId}/marketing/analytics/top-posts", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/analytics/top-posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "postId": { "type": "string", "format": "uuid" }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "scheduledForUtc": { "type": "string", "nullable": true }, "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number", "nullable": true }, "impressions": { "type": "number", "nullable": true }, "engagementScore": { "type": "number" }, "fetchedAt": { "type": "string" } }, "required": [ "postId", "publishedExternalId", "publishedUrl", "contentText", "scheduledForUtc", "likes", "reposts", "replies", "quotes", "bookmarks", "impressions", "engagementScore", "fetchedAt" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/analytics/x-account": { "get": { "operationId": "get_v1_orgs_orgId_marketing_analytics_x_account", "summary": "Get X account analytics", "description": "Whole-account numbers for the connected X account, including posts made outside AdVentur.ai: impressions, engagements, profile visits, likes, reposts, replies, bookmarks, posts and replies per day, and followers.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Whole-account numbers for the connected X account, including posts made outside AdVentur.ai: impressions, engagements, profile visits, likes, reposts, replies, bookmarks, posts and replies per day, and followers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account": { "type": "object", "properties": { "socialAccountId": { "type": "string", "format": "uuid" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "required": [ "socialAccountId", "handle", "name" ], "nullable": true }, "lastSyncedAt": { "type": "string", "nullable": true }, "windowDays": { "type": "integer" }, "totals": { "type": "object", "properties": { "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "engagementRate": { "type": "number", "nullable": true }, "profileVisits": { "type": "integer", "nullable": true }, "linkClicks": { "type": "integer", "nullable": true }, "likes": { "type": "integer" }, "reposts": { "type": "integer" }, "replies": { "type": "integer" }, "quotes": { "type": "integer" }, "bookmarks": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" } }, "required": [ "impressions", "engagements", "engagementRate", "profileVisits", "linkClicks", "likes", "reposts", "replies", "quotes", "bookmarks", "posts", "repliesSent" ] }, "previous": { "type": "object", "properties": { "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "engagementRate": { "type": "number", "nullable": true }, "profileVisits": { "type": "integer", "nullable": true }, "linkClicks": { "type": "integer", "nullable": true }, "likes": { "type": "integer" }, "reposts": { "type": "integer" }, "replies": { "type": "integer" }, "quotes": { "type": "integer" }, "bookmarks": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" } }, "required": [ "impressions", "engagements", "engagementRate", "profileVisits", "linkClicks", "likes", "reposts", "replies", "quotes", "bookmarks", "posts", "repliesSent" ], "nullable": true }, "audience": { "type": "object", "properties": { "followers": { "type": "integer", "nullable": true }, "followerChange": { "type": "integer", "nullable": true }, "following": { "type": "integer", "nullable": true }, "postCount": { "type": "integer", "nullable": true } }, "required": [ "followers", "followerChange", "following", "postCount" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" }, "followerChange": { "type": "integer", "nullable": true } }, "required": [ "date", "impressions", "engagements", "posts", "repliesSent", "followerChange" ] } } }, "required": [ "enabled", "account", "lastSyncedAt", "windowDays", "totals", "previous", "audience", "days" ] } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "put_v1_orgs_orgId_marketing_analytics_x_account", "summary": "Switch X account analytics on or off", "description": "Turns the daily read of the connected X account's own timeline on or off. Switching on reads the last 30 days straight away. Reads cost usage credits.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Turns the daily read of the connected X account's own timeline on or off. Switching on reads the last 30 days straight away. Reads cost usage credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account": { "type": "object", "properties": { "socialAccountId": { "type": "string", "format": "uuid" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } }, "required": [ "socialAccountId", "handle", "name" ], "nullable": true }, "lastSyncedAt": { "type": "string", "nullable": true }, "windowDays": { "type": "integer" }, "totals": { "type": "object", "properties": { "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "engagementRate": { "type": "number", "nullable": true }, "profileVisits": { "type": "integer", "nullable": true }, "linkClicks": { "type": "integer", "nullable": true }, "likes": { "type": "integer" }, "reposts": { "type": "integer" }, "replies": { "type": "integer" }, "quotes": { "type": "integer" }, "bookmarks": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" } }, "required": [ "impressions", "engagements", "engagementRate", "profileVisits", "linkClicks", "likes", "reposts", "replies", "quotes", "bookmarks", "posts", "repliesSent" ] }, "previous": { "type": "object", "properties": { "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "engagementRate": { "type": "number", "nullable": true }, "profileVisits": { "type": "integer", "nullable": true }, "linkClicks": { "type": "integer", "nullable": true }, "likes": { "type": "integer" }, "reposts": { "type": "integer" }, "replies": { "type": "integer" }, "quotes": { "type": "integer" }, "bookmarks": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" } }, "required": [ "impressions", "engagements", "engagementRate", "profileVisits", "linkClicks", "likes", "reposts", "replies", "quotes", "bookmarks", "posts", "repliesSent" ], "nullable": true }, "audience": { "type": "object", "properties": { "followers": { "type": "integer", "nullable": true }, "followerChange": { "type": "integer", "nullable": true }, "following": { "type": "integer", "nullable": true }, "postCount": { "type": "integer", "nullable": true } }, "required": [ "followers", "followerChange", "following", "postCount" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "impressions": { "type": "integer" }, "engagements": { "type": "integer" }, "posts": { "type": "integer" }, "repliesSent": { "type": "integer" }, "followerChange": { "type": "integer", "nullable": true } }, "required": [ "date", "impressions", "engagements", "posts", "repliesSent", "followerChange" ] } } }, "required": [ "enabled", "account", "lastSyncedAt", "windowDays", "totals", "previous", "audience", "days" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/content-research": { "post": { "operationId": "post_v1_orgs_orgId_marketing_content_research", "summary": "Research niche trends and generate review candidates", "description": "Enqueues a durable content_research agent job: web research for trending topics in the brand sector, inspiration import/analysis, and pending_approval post generation.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxTopics": { "type": "integer" }, "maxCandidates": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Enqueues a durable content_research agent job: web research for trending topics in the brand sector, inspiration import/analysis, and pending_approval post generation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enqueued": { "type": "boolean" }, "run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "jobType": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "payload": { "type": "object", "additionalProperties": {} }, "resultSummary": { "type": "object", "additionalProperties": {}, "nullable": true }, "attemptCount": { "type": "integer" }, "maxAttempts": { "type": "integer" }, "idempotencyKey": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "costCredits": { "type": "number", "nullable": true }, "estimatedCostMilliUsd": { "type": "number", "nullable": true }, "createdByUserId": { "type": "string", "format": "uuid", "nullable": true }, "startedAt": { "type": "string", "nullable": true }, "completedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "jobType", "status", "payload", "resultSummary", "attemptCount", "maxAttempts", "idempotencyKey", "errorMessage", "costCredits", "estimatedCostMilliUsd", "createdByUserId", "startedAt", "completedAt", "createdAt", "updatedAt" ], "nullable": true }, "skippedReason": { "type": "string", "enum": [ "concurrency_limit", "duplicate_active", "duplicate_idempotency", "queue_unavailable" ] } }, "required": [ "enqueued", "run" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/drafts": { "post": { "operationId": "post_v1_orgs_orgId_marketing_drafts", "summary": "Create a draft for review", "description": "Creates a post group with one variant per platform, in pending_approval. Never schedules or publishes.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "topic": { "type": "string" }, "objective": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid" }, "contentText": { "type": "string" }, "media": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ] }, "reddit": { "type": "object", "properties": { "subreddit": {}, "title": { "type": "string" } }, "required": [ "subreddit", "title" ] }, "youtube": { "type": "object", "properties": { "title": { "type": "string" }, "privacyStatus": { "type": "string", "enum": [ "public", "unlisted", "private" ] }, "madeForKids": { "type": "boolean" } } }, "tiktok": { "type": "object", "properties": { "title": { "type": "string" }, "isAigc": { "type": "boolean" }, "photoCoverIndex": { "type": "integer" } } }, "thread": { "type": "array", "items": { "type": "string" } }, "quoteTweetUrl": { "type": "string" }, "communityUrl": { "type": "string" }, "replySettings": { "type": "string", "enum": [ "everyone", "following", "mentionedUsers", "verified" ] }, "poll": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "string" } }, "durationMinutes": { "type": "integer" } }, "required": [ "options", "durationMinutes" ] } }, "required": [ "platform", "contentText" ] } } }, "required": [ "title", "posts" ] } } } }, "responses": { "200": { "description": "Creates a post group with one variant per platform, in pending_approval. Never schedules or publishes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } } }, "required": [ "group", "posts" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/linkedin-pages": { "get": { "operationId": "get_v1_orgs_orgId_marketing_linkedin_pages", "summary": "GET /v1/orgs/{orgId}/marketing/linkedin-pages", "description": "List the LinkedIn Pages offered after a LinkedIn Page sign-in.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "choice", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the LinkedIn Pages offered after a LinkedIn Page sign-in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "vanityName": { "type": "string", "nullable": true } }, "required": [ "id", "name", "vanityName" ] } } }, "required": [ "pages" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_marketing_linkedin_pages", "summary": "POST /v1/orgs/{orgId}/marketing/linkedin-pages", "description": "Connect the LinkedIn Pages picked after a LinkedIn Page sign-in.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "choice": { "type": "string" }, "organizationIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "choice", "organizationIds" ] } } } }, "responses": { "200": { "description": "Connect the LinkedIn Pages picked after a LinkedIn Page sign-in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "accountExternalId": { "type": "string" }, "accountName": { "type": "string", "nullable": true }, "accountHandle": { "type": "string", "nullable": true }, "profileImageUrl": { "type": "string", "format": "uri", "nullable": true }, "accountBio": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "format": "uri", "nullable": true }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenExpiresAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "xPremium": { "type": "boolean", "nullable": true }, "xSubscription": { "type": "string", "enum": [ "none", "basic", "premium", "premium_plus" ], "nullable": true } }, "required": [ "id", "orgId", "platform", "accountExternalId", "accountName", "accountHandle", "status", "scopes", "tokenExpiresAt", "lastRefreshedAt", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/media/{assetId}/complete": { "post": { "operationId": "post_v1_orgs_orgId_marketing_media_assetId_complete", "summary": "POST /v1/orgs/{orgId}/marketing/media/{assetId}/complete", "description": "Finalize a scheduler media upload after the client PUTs it to S3. For MP4 and MOV video the length and frame size are read from the file.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "assetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "contentType": { "type": "string" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "key", "kind", "contentType" ] } } } }, "responses": { "200": { "description": "Finalize a scheduler media upload after the client PUTs it to S3. For MP4 and MOV video the length and frame size are read from the file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "asset": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ] } }, "required": [ "asset" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/media/import": { "post": { "operationId": "post_v1_orgs_orgId_marketing_media_import", "summary": "POST /v1/orgs/{orgId}/marketing/media/import", "description": "Copy an image or video from a public https link into the workspace so it can be attached to posts.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "altText": { "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Copy an image or video from a public https link into the workspace so it can be attached to posts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "asset": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ] } }, "required": [ "asset" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/media": { "get": { "operationId": "get_v1_orgs_orgId_marketing_media", "summary": "List the media library", "description": "Lists the workspace's media library, newest first: files uploaded or imported, and on-brand visuals (branded images, carousels and app screenshots) rendered for it.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "uploads", "on_brand" ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "image", "video", "carousel" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lists the workspace's media library, newest first: files uploaded or imported, and on-brand visuals (branded images, carousels and app screenshots) rendered for it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "upload", "import", "branded_image", "carousel", "screenshot" ] }, "asset": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ] }, "previewUrl": { "type": "string", "format": "uri", "nullable": true }, "title": { "type": "string", "nullable": true }, "format": { "type": "string", "nullable": true }, "aiGenerated": { "type": "boolean" }, "sizeBytes": { "type": "integer" }, "createdAt": { "type": "string" } }, "required": [ "id", "source", "asset", "previewUrl", "title", "format", "aiGenerated", "sizeBytes", "createdAt" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" }, "counts": { "type": "object", "properties": { "all": { "type": "integer" }, "uploads": { "type": "integer" }, "onBrand": { "type": "integer" } }, "required": [ "all", "uploads", "onBrand" ] } }, "required": [ "items", "page", "limit", "total", "hasMore", "counts" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/media/upload-url": { "post": { "operationId": "post_v1_orgs_orgId_marketing_media_upload_url", "summary": "POST /v1/orgs/{orgId}/marketing/media/upload-url", "description": "Get a presigned URL to upload a scheduler post's image or video asset.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "video" ] }, "contentType": { "type": "string" } }, "required": [ "kind", "contentType" ] } } } }, "responses": { "200": { "description": "Get a presigned URL to upload a scheduler post's image or video asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string" }, "key": { "type": "string" }, "expiresInSeconds": { "type": "number" }, "method": { "const": "PUT", "type": "string" }, "requiredHeaders": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "assetId", "uploadUrl", "key", "expiresInSeconds", "method", "requiredHeaders" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/post-groups/{groupId}/approve": { "post": { "operationId": "post_v1_orgs_orgId_marketing_post_groups_groupId_approve", "summary": "Approve a post group", "description": "Approve candidate content. By default, AdVentur auto-assigns the best available publishing slot.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvePosts": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "autoSchedule": { "type": "boolean" }, "scheduledForUtc": { "type": "string" }, "timezone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Approve candidate content. By default, AdVentur auto-assigns the best available publishing slot.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/post-groups/{groupId}": { "patch": { "operationId": "patch_v1_orgs_orgId_marketing_post_groups_groupId", "summary": "PATCH /v1/orgs/{orgId}/marketing/post-groups/{groupId}", "description": "Partial update. Omitted keys are unchanged (status-only PATCH keeps title/topic/objective). Editing title/topic/objective on approved or scheduled content returns the group to pending_approval.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "topic": { "type": "string" }, "objective": { "type": "string" }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Partial update. Omitted keys are unchanged (status-only PATCH keeps title/topic/objective). Editing title/topic/objective on approved or scheduled content returns the group to pending_approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/post-groups/{groupId}/reject": { "post": { "operationId": "post_v1_orgs_orgId_marketing_post_groups_groupId_reject", "summary": "Reject a post group", "description": "Reject candidate content quickly. Optional lightweight reasons improve preference learning.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rejectPosts": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "reason": { "type": "string", "enum": [ "not_my_voice", "not_interesting", "too_promotional", "inaccurate", "repetitive", "wrong_timing", "other" ] }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Reject candidate content quickly. Optional lightweight reasons improve preference learning.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/post-groups/{groupId}/schedule": { "post": { "operationId": "post_v1_orgs_orgId_marketing_post_groups_groupId_schedule", "summary": "Schedule a post group", "description": "Schedule approved content at an explicit UTC time or the best available slot (useBestSlot). Groups in draft or pending_approval are rejected with HTTP 409.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledForUtc": { "type": "string" }, "useBestSlot": { "type": "boolean" }, "timezone": { "type": "string" }, "postIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "description": "Schedule approved content at an explicit UTC time or the best available slot (useBestSlot). Groups in draft or pending_approval are rejected with HTTP 409.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/post-groups": { "post": { "operationId": "post_v1_orgs_orgId_marketing_post_groups", "summary": "POST /v1/orgs/{orgId}/marketing/post-groups", "description": "POST /v1/orgs/{orgId}/marketing/post-groups", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "topic": { "type": "string" }, "objective": { "type": "string" }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "strategyId": { "type": "string", "format": "uuid" }, "strategyVersion": { "type": "integer" }, "pillarId": { "type": "string" }, "priorityId": { "type": "string" }, "contentType": { "type": "string" }, "opportunityId": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid" }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {} }, "platformPayload": { "type": "object", "additionalProperties": {} }, "replySettings": { "type": "string", "enum": [ "everyone", "following", "mentionedUsers", "verified" ] } }, "required": [ "platform", "contentText" ] } } }, "required": [ "title", "posts" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/post-groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } } }, "required": [ "group", "posts" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/posts/{postId}": { "patch": { "operationId": "patch_v1_orgs_orgId_marketing_posts_postId", "summary": "PATCH /v1/orgs/{orgId}/marketing/posts/{postId}", "description": "Partial update. Omitted keys are unchanged (status-only PATCH keeps contentText). Editing contentText/media/platformPayload on approved, scheduled, or failed content invalidates approval.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "socialAccountId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string" }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {} }, "platformPayload": { "type": "object", "additionalProperties": {} }, "quoteTweetUrl": { "type": "string", "nullable": true }, "communityUrl": { "type": "string", "nullable": true }, "replySettings": { "type": "string", "enum": [ "everyone", "following", "mentionedUsers", "verified" ], "nullable": true }, "poll": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "string" } }, "durationMinutes": { "type": "integer" } }, "required": [ "options", "durationMinutes" ], "nullable": true } } } } } }, "responses": { "200": { "description": "Partial update. Omitted keys are unchanged (status-only PATCH keeps contentText). Editing contentText/media/platformPayload on approved, scheduled, or failed content invalidates approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_marketing_posts_postId", "summary": "DELETE /v1/orgs/{orgId}/marketing/posts/{postId}", "description": "DELETE /v1/orgs/{orgId}/marketing/posts/{postId}", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/marketing/posts/{postId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/posts/{postId}/post-now": { "post": { "operationId": "post_v1_orgs_orgId_marketing_posts_postId_post_now", "summary": "POST /v1/orgs/{orgId}/marketing/posts/{postId}/post-now", "description": "Publish an approved or scheduled post immediately. Draft and pending_approval return HTTP 409 until a human approves.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "postId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Publish an approved or scheduled post immediately. Draft and pending_approval return HTTP 409 until a human approves.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/posts": { "get": { "operationId": "get_v1_orgs_orgId_marketing_posts", "summary": "GET /v1/orgs/{orgId}/marketing/posts", "description": "GET /v1/orgs/{orgId}/marketing/posts", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduledForUtc", "createdAt", "status", "platform" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string" }, "socialAccountId": { "type": "string" }, "tagId": { "type": "string" }, "scheduledFrom": { "type": "string" }, "scheduledTo": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "eq", "in" ] }, "status": { "type": "string", "enum": [ "eq", "in" ] }, "socialAccountId": { "type": "string", "enum": [ "eq" ] }, "tagId": { "type": "string", "enum": [ "eq", "in" ] }, "scheduledFrom": { "type": "string", "enum": [ "gte" ] }, "scheduledTo": { "type": "string", "enum": [ "lte" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/rewrite": { "post": { "operationId": "post_v1_orgs_orgId_marketing_rewrite", "summary": "POST /v1/orgs/{orgId}/marketing/rewrite", "description": "POST /v1/orgs/{orgId}/marketing/rewrite", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "tone": { "type": "string" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "variantCount": { "type": "integer" }, "instruction": { "type": "string" }, "maxLength": { "type": "integer" } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/rewrite", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "variations": { "type": "array", "items": { "type": "object", "properties": { "styleKey": { "type": "string" }, "text": { "type": "string" } }, "required": [ "styleKey", "text" ] } }, "provider": { "type": "string" }, "providerModel": { "type": "string" }, "promptVersion": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" } }, "required": [ "variations", "provider", "providerModel", "promptVersion", "creditsUsed", "remainingCredits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/scheduler/events": { "get": { "operationId": "get_v1_orgs_orgId_marketing_scheduler_events", "summary": "GET /v1/orgs/{orgId}/marketing/scheduler/events", "description": "GET /v1/orgs/{orgId}/marketing/scheduler/events", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduledForUtc", "createdAt", "status", "platform" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "status": { "type": "string" }, "socialAccountId": { "type": "string" }, "tagId": { "type": "string" }, "scheduledFrom": { "type": "string" }, "scheduledTo": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "eq", "in" ] }, "status": { "type": "string", "enum": [ "eq", "in" ] }, "socialAccountId": { "type": "string", "enum": [ "eq" ] }, "tagId": { "type": "string", "enum": [ "eq", "in" ] }, "scheduledFrom": { "type": "string", "enum": [ "gte" ] }, "scheduledTo": { "type": "string", "enum": [ "lte" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/scheduler/events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/scheduler/schedule-coverage": { "get": { "operationId": "get_v1_orgs_orgId_marketing_scheduler_schedule_coverage", "summary": "Get schedule coverage", "description": "Derived schedule-coverage state for the next N days (gaps, clustering, pending approval).", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Derived schedule-coverage state for the next N days (gaps, clustering, pending approval).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "timezone": { "type": "string" }, "overallStatus": { "type": "string", "enum": [ "covered", "needs_attention" ] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "scheduledCount": { "type": "integer" }, "publishedCount": { "type": "integer" }, "pendingApprovalCount": { "type": "integer" }, "targetPosts": { "type": "number", "nullable": true }, "status": { "type": "string", "enum": [ "covered", "gap", "clustered", "waiting" ] }, "nextGapAt": { "type": "string", "nullable": true }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "platform", "scheduledCount", "publishedCount", "pendingApprovalCount", "targetPosts", "status", "nextGapAt", "notes" ] } }, "pendingApprovalTotal": { "type": "integer" } }, "required": [ "windowDays", "timezone", "overallStatus", "channels", "pendingApprovalTotal" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/scheduler/settings": { "get": { "operationId": "get_v1_orgs_orgId_marketing_scheduler_settings", "summary": "Get scheduling settings", "description": "The workspace's scheduling profile: audience type and timezone, posting windows per platform, blackout dates, spacing and daily limits. Unset fields show the defaults for the audience type.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace's scheduling profile: audience type and timezone, posting windows per platform, blackout dates, spacing and daily limits. Unset fields show the defaults for the audience type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "timezone": { "type": "string" }, "timezoneIsSet": { "type": "boolean" }, "audienceTimezone": { "type": "string", "nullable": true }, "effectiveTimezone": { "type": "string" }, "audienceType": { "type": "string", "enum": [ "b2b", "b2c", "mixed" ] }, "includeWeekends": { "type": "boolean" }, "postingWindows": { "type": "object", "properties": { "x": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } }, "linkedin": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } }, "tiktok": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } } }, "required": [ "x", "linkedin", "tiktok" ] }, "customPostingWindows": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin", "tiktok" ] } }, "blackoutDates": { "type": "array", "items": { "type": "string" } }, "minGapMinutes": { "type": "integer" }, "maxPostsPerDay": { "type": "integer" }, "ownerAvailability": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "days", "start", "end" ] } } }, "required": [ "timezone", "timezoneIsSet", "audienceTimezone", "effectiveTimezone", "audienceType", "includeWeekends", "postingWindows", "customPostingWindows", "blackoutDates", "minGapMinutes", "maxPostsPerDay", "ownerAvailability" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_marketing_scheduler_settings", "summary": "Update scheduling settings", "description": "Change part of the scheduling profile. Fields left out stay as they are. Owner/admin only.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "audienceTimezone": { "type": "string", "nullable": true }, "audienceType": { "type": "string", "enum": [ "b2b", "b2c", "mixed" ] }, "includeWeekends": { "type": "boolean", "nullable": true }, "postingWindows": { "type": "object", "properties": { "x": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end" ] } }, "linkedin": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end" ] } }, "tiktok": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end" ] } } } }, "blackoutDates": { "type": "array", "items": { "type": "string" } }, "minGapMinutes": { "type": "integer" }, "maxPostsPerDay": { "type": "integer" }, "ownerAvailability": { "type": "array", "items": { "type": "object", "properties": { "days": {}, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "days", "start", "end" ] } }, "timezone": {}, "resetPostingWindows": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin", "tiktok" ] } } } } } } }, "responses": { "200": { "description": "Change part of the scheduling profile. Fields left out stay as they are. Owner/admin only.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "timezone": { "type": "string" }, "timezoneIsSet": { "type": "boolean" }, "audienceTimezone": { "type": "string", "nullable": true }, "effectiveTimezone": { "type": "string" }, "audienceType": { "type": "string", "enum": [ "b2b", "b2c", "mixed" ] }, "includeWeekends": { "type": "boolean" }, "postingWindows": { "type": "object", "properties": { "x": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } }, "linkedin": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } }, "tiktok": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "days", "start", "end", "weight" ] } } }, "required": [ "x", "linkedin", "tiktok" ] }, "customPostingWindows": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin", "tiktok" ] } }, "blackoutDates": { "type": "array", "items": { "type": "string" } }, "minGapMinutes": { "type": "integer" }, "maxPostsPerDay": { "type": "integer" }, "ownerAvailability": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer" } }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "days", "start", "end" ] } } }, "required": [ "timezone", "timezoneIsSet", "audienceTimezone", "effectiveTimezone", "audienceType", "includeWeekends", "postingWindows", "customPostingWindows", "blackoutDates", "minGapMinutes", "maxPostsPerDay", "ownerAvailability" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/scheduler/slots": { "get": { "operationId": "get_v1_orgs_orgId_marketing_scheduler_slots", "summary": "Suggest publishing slots", "description": "Ranks the best upcoming publishing times for a platform from the workspace's scheduling profile and its own post results, skipping times that clash with scheduled posts. Each slot says why it was picked.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "x", "linkedin", "tiktok" ] } }, { "name": "contentType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ranks the best upcoming publishing times for a platform from the workspace's scheduling profile and its own post results, skipping times that clash with scheduled posts. Each slot says why it was picked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "timezone": { "type": "string" }, "audienceType": { "type": "string", "enum": [ "b2b", "b2c", "mixed" ] }, "historyPosts": { "type": "integer" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "scheduledForUtc": { "type": "string" }, "localDate": { "type": "string" }, "localTime": { "type": "string" }, "weekday": { "type": "string" }, "score": { "type": "number" }, "reason": { "type": "string" }, "basis": { "type": "string", "enum": [ "defaults", "history" ] } }, "required": [ "scheduledForUtc", "localDate", "localTime", "weekday", "score", "reason", "basis" ] } } }, "required": [ "timezone", "audienceType", "historyPosts", "slots" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/scheduler/suggested-times": { "get": { "operationId": "get_v1_orgs_orgId_marketing_scheduler_suggested_times", "summary": "GET /v1/orgs/{orgId}/marketing/scheduler/suggested-times", "description": "GET /v1/orgs/{orgId}/marketing/scheduler/suggested-times", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/scheduler/suggested-times", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "localTime": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "localTime", "reason" ] } } }, "required": [ "suggestions" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/settings": { "get": { "operationId": "get_v1_orgs_orgId_marketing_settings", "summary": "GET /v1/orgs/{orgId}/marketing/settings", "description": "GET /v1/orgs/{orgId}/marketing/settings", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "teamsEnabled": { "type": "boolean" }, "approvalRequired": { "type": "boolean" }, "allowBypassApproval": { "type": "boolean" } }, "required": [ "teamsEnabled", "approvalRequired", "allowBypassApproval" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_marketing_settings", "summary": "PATCH /v1/orgs/{orgId}/marketing/settings", "description": "PATCH /v1/orgs/{orgId}/marketing/settings", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalRequired": { "type": "boolean" } }, "required": [ "approvalRequired" ] } } } }, "responses": { "200": { "description": "PATCH /v1/orgs/{orgId}/marketing/settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "teamsEnabled": { "type": "boolean" }, "approvalRequired": { "type": "boolean" }, "allowBypassApproval": { "type": "boolean" } }, "required": [ "teamsEnabled", "approvalRequired", "allowBypassApproval" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/suggestions/generate": { "post": { "operationId": "post_v1_orgs_orgId_marketing_suggestions_generate", "summary": "POST /v1/orgs/{orgId}/marketing/suggestions/generate", "description": "POST /v1/orgs/{orgId}/marketing/suggestions/generate", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid" }, "topic": { "type": "string" }, "objective": { "type": "string" }, "tone": { "type": "string" }, "stylePreference": { "type": "string", "enum": [ "full", "hook_only" ] }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] } }, "constraints": { "type": "object", "additionalProperties": {} } }, "required": [ "topic", "platforms" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/suggestions/generate", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid", "nullable": true }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "styleKey": { "type": "string" }, "text": { "type": "string" }, "mediaGuidance": { "type": "object", "additionalProperties": {}, "nullable": true }, "provider": { "type": "string" }, "providerModel": { "type": "string", "nullable": true }, "promptVersion": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "orgId", "groupId", "platform", "styleKey", "text", "mediaGuidance", "provider", "providerModel", "promptVersion", "createdAt" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/tags/{tagId}": { "patch": { "operationId": "patch_v1_orgs_orgId_marketing_tags_tagId", "summary": "PATCH /v1/orgs/{orgId}/marketing/tags/{tagId}", "description": "PATCH /v1/orgs/{orgId}/marketing/tags/{tagId}", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } } } } } }, "responses": { "200": { "description": "PATCH /v1/orgs/{orgId}/marketing/tags/{tagId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "name", "color", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_marketing_tags_tagId", "summary": "DELETE /v1/orgs/{orgId}/marketing/tags/{tagId}", "description": "DELETE /v1/orgs/{orgId}/marketing/tags/{tagId}", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/marketing/tags/{tagId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "name", "color", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/tags": { "get": { "operationId": "get_v1_orgs_orgId_marketing_tags", "summary": "GET /v1/orgs/{orgId}/marketing/tags", "description": "GET /v1/orgs/{orgId}/marketing/tags", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/marketing/tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "name", "color", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_marketing_tags", "summary": "POST /v1/orgs/{orgId}/marketing/tags", "description": "POST /v1/orgs/{orgId}/marketing/tags", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "POST /v1/orgs/{orgId}/marketing/tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "name", "color", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/threads": { "post": { "operationId": "post_v1_orgs_orgId_marketing_threads", "summary": "Draft an X thread for review", "description": "Creates an X thread in pending_approval: the first post plus replies that follow it. Never schedules or publishes.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "topic": { "type": "string" }, "objective": { "type": "string" }, "posts": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "numbered": { "type": "boolean" }, "socialAccountId": { "type": "string", "format": "uuid" }, "media": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ] }, "quoteTweetUrl": { "type": "string" }, "communityUrl": { "type": "string" }, "replySettings": { "type": "string", "enum": [ "everyone", "following", "mentionedUsers", "verified" ] }, "poll": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "string" } }, "durationMinutes": { "type": "integer" } }, "required": [ "options", "durationMinutes" ] } }, "required": [ "title" ] } } } }, "responses": { "200": { "description": "Creates an X thread in pending_approval: the first post plus replies that follow it. Never schedules or publishes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } } }, "required": [ "group", "posts" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/visuals/carousel": { "post": { "operationId": "post_v1_orgs_orgId_marketing_visuals_carousel", "summary": "POST /v1/orgs/{orgId}/marketing/visuals/carousel", "description": "Render a branded carousel (2 to 15 slides) as a PDF document for LinkedIn and as PNG slides for Instagram and X.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "portrait", "square" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "bullets": { "type": "array", "items": { "type": "string" } }, "stat": { "type": "string" }, "attribution": { "type": "string" }, "cta": { "type": "string" }, "layout": { "type": "string", "enum": [ "cover", "point", "stat", "quote", "list", "cta" ] } }, "required": [ "title" ] } }, "aiBackground": { "type": "object", "properties": { "prompt": { "type": "string" }, "model": { "type": "string" } }, "required": [ "prompt" ] }, "outputs": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "png" ] } } }, "required": [ "slides" ] } } } }, "responses": { "200": { "description": "Render a branded carousel (2 to 15 slides) as a PDF document for LinkedIn and as PNG slides for Instagram and X.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "pageCount": { "type": "integer" } }, "required": [ "assetId", "url", "contentType", "sizeBytes", "pageCount" ], "nullable": true }, "slides": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "page": { "type": "integer" } }, "required": [ "assetId", "url", "contentType", "sizeBytes", "width", "height", "format" ] } }, "postMedia": { "type": "object", "properties": { "linkedin": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true }, "x": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true }, "facebook": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true }, "instagram": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true } }, "required": [ "linkedin", "x", "facebook", "instagram" ] }, "aiBackground": { "type": "object", "properties": { "model": { "type": "string" }, "estimatedCostMilliUsd": { "type": "number" } }, "required": [ "model", "estimatedCostMilliUsd" ], "nullable": true }, "renderMs": { "type": "integer" } }, "required": [ "document", "slides", "postMedia", "aiBackground", "renderMs" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/visuals/image": { "post": { "operationId": "post_v1_orgs_orgId_marketing_visuals_image", "summary": "POST /v1/orgs/{orgId}/marketing/visuals/image", "description": "Render a branded image from a template in the workspace's colours, fonts and logo, in one or more formats, optionally over your own photo or an AI-generated background.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "headline", "quote", "stat", "list", "photo" ] }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "content": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "bullets": { "type": "array", "items": { "type": "string" } }, "stat": { "type": "string" }, "attribution": { "type": "string" }, "cta": { "type": "string" } }, "required": [ "title" ] }, "backgroundImage": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" } } }, "aiBackground": { "type": "object", "properties": { "prompt": { "type": "string" }, "model": { "type": "string" } }, "required": [ "prompt" ] }, "alsoFormats": { "type": "array", "items": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] } }, "outputs": { "type": "array", "items": { "type": "string", "enum": [ "png", "svg" ] } } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Render a branded image from a template in the workspace's colours, fonts and logo, in one or more formats, optionally over your own photo or an AI-generated background.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "page": { "type": "integer" } }, "required": [ "assetId", "url", "contentType", "sizeBytes", "width", "height", "format" ] } }, "postMedia": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true }, "aiBackground": { "type": "object", "properties": { "model": { "type": "string" }, "estimatedCostMilliUsd": { "type": "number" } }, "required": [ "model", "estimatedCostMilliUsd" ], "nullable": true }, "renderMs": { "type": "integer" } }, "required": [ "images", "postMedia", "aiBackground", "renderMs" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/visuals/options": { "get": { "operationId": "get_v1_orgs_orgId_marketing_visuals_options", "summary": "GET /v1/orgs/{orgId}/marketing/visuals/options", "description": "Formats, templates, themes, carousel layouts and AI image models available for branded visuals, plus the brand colours, fonts and logo they will use.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includeAllModels", "in": "query", "required": true, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Formats, templates, themes, carousel layouts and AI image models available for branded visuals, plus the brand colours, fonts and logo they will use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "label": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspectRatio": { "type": "string" }, "useFor": { "type": "string" } }, "required": [ "id", "label", "width", "height", "aspectRatio", "useFor" ] } }, "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "headline", "quote", "stat", "list", "photo" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "description", "fields" ] } }, "themes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "label", "description" ] } }, "carousel": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "string", "enum": [ "portrait", "square" ] } }, "layouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "cover", "point", "stat", "quote", "list", "cta" ] }, "description": { "type": "string" } }, "required": [ "id", "description" ] } }, "minSlides": { "type": "integer" }, "maxSlides": { "type": "integer" } }, "required": [ "formats", "layouts", "minSlides", "maxSlides" ] }, "screenshot": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "string", "enum": [ "landscape", "square", "portrait", "link", "story" ] } }, "layouts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "centered", "tilted", "closeup" ] }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "label", "description" ] } } }, "required": [ "formats", "layouts" ] }, "aiBackground": { "type": "object", "properties": { "available": { "type": "boolean" }, "defaultModel": { "type": "string" }, "recommendedModels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "useFor": { "type": "string" } }, "required": [ "id", "useFor" ] } }, "models": { "type": "array", "items": { "type": "string" } }, "totalModels": { "type": "integer" } }, "required": [ "available", "defaultModel", "recommendedModels", "totalModels" ] }, "brand": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" } }, "headingFont": { "type": "string" }, "bodyFont": { "type": "string" }, "background": { "type": "string", "nullable": true }, "hasLogo": { "type": "boolean" }, "logo": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "width", "height" ], "nullable": true } }, "required": [ "colors", "headingFont", "bodyFont", "background", "hasLogo", "logo" ] } }, "required": [ "formats", "templates", "themes", "carousel", "screenshot", "aiBackground", "brand" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/visuals/preview": { "post": { "operationId": "post_v1_orgs_orgId_marketing_visuals_preview", "summary": "POST /v1/orgs/{orgId}/marketing/visuals/preview", "description": "Render a branded image, framed screenshot or every slide of a carousel small and return it inline as PNG data URIs, for a live preview while editing. Nothing is stored.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "template": { "type": "string", "enum": [ "headline", "quote", "stat", "list", "photo" ] }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "content": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "bullets": { "type": "array", "items": { "type": "string" } }, "stat": { "type": "string" }, "attribution": { "type": "string" }, "cta": { "type": "string" } }, "required": [ "title" ] }, "backgroundImage": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" } } } }, "required": [ "kind", "content" ] }, { "type": "object", "properties": { "kind": { "const": "screenshot", "type": "string" }, "screenshot": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" } } }, "layout": { "type": "string", "enum": [ "centered", "tilted", "closeup" ] }, "format": { "type": "string", "enum": [ "landscape", "square", "portrait", "link", "story" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "content": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" } } }, "addressBar": { "type": "string" }, "windowTheme": { "type": "string", "enum": [ "auto", "light", "dark" ] }, "crop": { "type": "object", "properties": { "zoom": { "type": "number" }, "focusX": { "type": "number" }, "focusY": { "type": "number" } } } }, "required": [ "kind", "screenshot" ] }, { "type": "object", "properties": { "kind": { "const": "carousel", "type": "string" }, "format": { "type": "string", "enum": [ "portrait", "square" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "slides": { "type": "array", "items": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "bullets": { "type": "array", "items": { "type": "string" } }, "stat": { "type": "string" }, "attribution": { "type": "string" }, "cta": { "type": "string" }, "layout": { "type": "string", "enum": [ "cover", "point", "stat", "quote", "list", "cta" ] } }, "required": [ "title" ] } } }, "required": [ "kind", "slides" ] } ] } } } }, "responses": { "200": { "description": "Render a branded image, framed screenshot or every slide of a carousel small and return it inline as PNG data URIs, for a live preview while editing. Nothing is stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "image": { "type": "string" }, "slides": { "type": "array", "items": { "type": "string" } }, "width": { "type": "integer" }, "height": { "type": "integer" }, "renderMs": { "type": "integer" } }, "required": [ "image", "width", "height", "renderMs" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/visuals/screenshot": { "post": { "operationId": "post_v1_orgs_orgId_marketing_visuals_screenshot", "summary": "POST /v1/orgs/{orgId}/marketing/visuals/screenshot", "description": "Frame an app screenshot in a Mac-style browser window on a branded canvas, with an optional headline, in one or more formats.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenshot": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" } } }, "layout": { "type": "string", "enum": [ "centered", "tilted", "closeup" ] }, "format": { "type": "string", "enum": [ "landscape", "square", "portrait", "link", "story" ] }, "theme": { "type": "string", "enum": [ "brand", "light", "dark" ] }, "includeLogo": { "type": "boolean" }, "handle": { "type": "string" }, "content": { "type": "object", "properties": { "eyebrow": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" } } }, "addressBar": { "type": "string" }, "windowTheme": { "type": "string", "enum": [ "auto", "light", "dark" ] }, "crop": { "type": "object", "properties": { "zoom": { "type": "number" }, "focusX": { "type": "number" }, "focusY": { "type": "number" } } }, "alsoFormats": { "type": "array", "items": { "type": "string", "enum": [ "landscape", "square", "portrait", "link", "story" ] } }, "outputs": { "type": "array", "items": { "type": "string", "enum": [ "png", "svg" ] } } }, "required": [ "screenshot" ] } } } }, "responses": { "200": { "description": "Frame an app screenshot in a Mac-style browser window on a branded canvas, with an optional headline, in one or more formats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "page": { "type": "integer" } }, "required": [ "assetId", "url", "contentType", "sizeBytes", "width", "height", "format" ] } }, "postMedia": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "image", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes" ] }, { "type": "object", "properties": { "kind": { "const": "images", "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "altText": { "type": "string" } }, "required": [ "assetId", "url", "contentType", "sizeBytes" ] } } }, "required": [ "kind", "images" ] }, { "type": "object", "properties": { "kind": { "const": "document", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "const": "application/pdf", "type": "string" }, "sizeBytes": { "type": "integer" }, "title": { "type": "string" }, "pageCount": { "type": "integer" }, "previewImageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "title" ] }, { "type": "object", "properties": { "kind": { "const": "video", "type": "string" }, "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "durationSeconds": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "required": [ "kind", "assetId", "url", "contentType", "sizeBytes", "durationSeconds", "width", "height" ] } ], "nullable": true }, "aiBackground": { "type": "object", "properties": { "model": { "type": "string" }, "estimatedCostMilliUsd": { "type": "number" } }, "required": [ "model", "estimatedCostMilliUsd" ], "nullable": true }, "renderMs": { "type": "integer" } }, "required": [ "images", "postMedia", "aiBackground", "renderMs" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/x-posts/delete": { "post": { "operationId": "post_v1_orgs_orgId_marketing_x_posts_delete", "summary": "Delete an X post", "description": "Deletes one of the workspace's own X posts, named by its link on X or by its post id. A published post is deleted on X and removed here; one that hasn't gone out yet is canceled.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postUrl": { "type": "string" }, "postId": { "type": "string", "format": "uuid" }, "socialAccountId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Deletes one of the workspace's own X posts, named by its link on X or by its post id. A published post is deleted on X and removed here; one that hasn't gone out yet is canceled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "deleted_on_x", "removed_from_schedule" ] }, "postId": { "type": "string", "nullable": true }, "xPostId": { "type": "string", "nullable": true }, "socialAccountId": { "type": "string", "nullable": true }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "outcome", "postId", "xPostId", "socialAccountId", "warnings" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/x-posts/read": { "post": { "operationId": "post_v1_orgs_orgId_marketing_x_posts_read", "summary": "Read a post on X", "description": "Reads any public post on X by its link or id: full text, author, metrics, links, hashtags, mentions and the posts it replies to or quotes, plus its photos and videos when asked. Each post X returns costs usage credits.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "string" }, "includeMedia": { "type": "boolean" } }, "required": [ "post" ] } } } }, "responses": { "200": { "description": "Reads any public post on X by its link or id: full text, author, metrics, links, hashtags, mentions and the posts it replies to or quotes, plus its photos and videos when asked. Each post X returns costs usage credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "followers": { "type": "number", "nullable": true }, "profileImageUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } }, "required": [ "id", "handle", "name", "verified", "followers", "profileImageUrl", "bio" ], "nullable": true }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": { "type": "string", "nullable": true }, "inReplyToPostId": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } }, "referencedPosts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ] }, "id": { "type": "string" }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": {}, "lang": {}, "author": {}, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": {}, "inReplyToPostId": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media" ], "nullable": true } }, "required": [ "type", "id", "post" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media", "referencedPosts" ] }, "usage": { "type": "object", "properties": { "postsReturned": { "type": "number" }, "postsCharged": { "type": "number" }, "creditsUsed": { "type": "number" } }, "required": [ "postsReturned", "postsCharged", "creditsUsed" ] } }, "required": [ "post", "usage" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/marketing/x-posts/thread": { "post": { "operationId": "post_v1_orgs_orgId_marketing_x_posts_thread", "summary": "Read a conversation on X", "description": "Reads the conversation a post on X belongs to: the post that started it, the author's own thread oldest first and, when asked, other people's replies. Each post X returns costs usage credits.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "post": { "type": "string" }, "includeReplies": { "type": "boolean" }, "includeMedia": { "type": "boolean" }, "limit": { "type": "integer" } }, "required": [ "post" ] } } } }, "responses": { "200": { "description": "Reads the conversation a post on X belongs to: the post that started it, the author's own thread oldest first and, when asked, other people's replies. Each post X returns costs usage credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "followers": { "type": "number", "nullable": true }, "profileImageUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } }, "required": [ "id", "handle", "name", "verified", "followers", "profileImageUrl", "bio" ], "nullable": true }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": { "type": "string", "nullable": true }, "inReplyToPostId": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } }, "referencedPosts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ] }, "id": { "type": "string" }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": {}, "lang": {}, "author": {}, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": {}, "inReplyToPostId": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media" ], "nullable": true } }, "required": [ "type", "id", "post" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media", "referencedPosts" ] }, "root": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "followers": { "type": "number", "nullable": true }, "profileImageUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } }, "required": [ "id", "handle", "name", "verified", "followers", "profileImageUrl", "bio" ], "nullable": true }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": { "type": "string", "nullable": true }, "inReplyToPostId": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } }, "referencedPosts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ] }, "id": { "type": "string" }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": {}, "lang": {}, "author": {}, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": {}, "inReplyToPostId": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media" ], "nullable": true } }, "required": [ "type", "id", "post" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media", "referencedPosts" ], "nullable": true }, "thread": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "followers": { "type": "number", "nullable": true }, "profileImageUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } }, "required": [ "id", "handle", "name", "verified", "followers", "profileImageUrl", "bio" ], "nullable": true }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": { "type": "string", "nullable": true }, "inReplyToPostId": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } }, "referencedPosts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ] }, "id": { "type": "string" }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": {}, "lang": {}, "author": {}, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": {}, "inReplyToPostId": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media" ], "nullable": true } }, "required": [ "type", "id", "post" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media", "referencedPosts" ] } }, "replies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "verified": { "type": "boolean" }, "followers": { "type": "number", "nullable": true }, "profileImageUrl": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true } }, "required": [ "id", "handle", "name", "verified", "followers", "profileImageUrl", "bio" ], "nullable": true }, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": { "type": "string", "nullable": true }, "inReplyToPostId": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } }, "referencedPosts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "replied_to", "quoted", "retweeted" ] }, "id": { "type": "string" }, "post": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "createdAt": {}, "lang": {}, "author": {}, "metrics": { "type": "object", "properties": { "likes": { "type": "number" }, "reposts": { "type": "number" }, "replies": { "type": "number" }, "quotes": { "type": "number" }, "bookmarks": { "type": "number" }, "impressions": { "type": "number", "nullable": true } }, "required": [ "likes", "reposts", "replies", "quotes", "bookmarks", "impressions" ] }, "conversationId": {}, "inReplyToPostId": {}, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "expandedUrl": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "required": [ "url", "expandedUrl", "title", "description" ] } }, "hashtags": { "type": "array", "items": { "type": "string" } }, "mentions": { "type": "array", "items": { "type": "string" } }, "cashtags": { "type": "array", "items": { "type": "string" } }, "possiblySensitive": { "type": "boolean" }, "mediaCount": { "type": "number" }, "media": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "photo", "video", "animated_gif" ] }, "url": { "type": "string", "nullable": true }, "previewImageUrl": { "type": "string", "nullable": true }, "altText": { "type": "string", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "contentType": { "type": "string" }, "bitRate": { "type": "number", "nullable": true } }, "required": [ "url", "contentType", "bitRate" ] } } }, "required": [ "key", "type", "url", "previewImageUrl", "altText", "width", "height", "durationMs", "variants" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media" ], "nullable": true } }, "required": [ "type", "id", "post" ] } } }, "required": [ "id", "url", "text", "createdAt", "lang", "author", "metrics", "conversationId", "inReplyToPostId", "links", "hashtags", "mentions", "cashtags", "possiblySensitive", "mediaCount", "media", "referencedPosts" ] } }, "truncated": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } }, "usage": { "type": "object", "properties": { "postsReturned": { "type": "number" }, "postsCharged": { "type": "number" }, "creditsUsed": { "type": "number" } }, "required": [ "postsReturned", "postsCharged", "creditsUsed" ] } }, "required": [ "post", "root", "thread", "replies", "truncated", "notes", "usage" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/members/{memberId}": { "patch": { "operationId": "patch_v1_orgs_orgId_members_memberId", "summary": "PATCH /v1/orgs/{orgId}/members/{memberId}", "description": "PATCH /v1/orgs/{orgId}/members/{memberId}", "tags": [ "members" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roleKey": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended" ] } } } } } }, "responses": { "200": { "description": "PATCH /v1/orgs/{orgId}/members/{memberId}", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "roleId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "nullable": true } }, "required": [ "id", "roleId", "status" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_members_memberId", "summary": "DELETE /v1/orgs/{orgId}/members/{memberId}", "description": "DELETE /v1/orgs/{orgId}/members/{memberId}", "tags": [ "members" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DELETE /v1/orgs/{orgId}/members/{memberId}", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/orgs/{orgId}/members": { "get": { "operationId": "get_v1_orgs_orgId_members", "summary": "GET /v1/orgs/{orgId}/members", "description": "GET /v1/orgs/{orgId}/members", "tags": [ "members" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "joinedAt", "createdAt", "role", "status", "email", "name" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string" }, "roleKey": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "eq", "in" ] }, "roleKey": { "type": "string", "enum": [ "eq", "in" ] }, "email": { "type": "string", "enum": [ "eq", "contains" ] }, "name": { "type": "string", "enum": [ "eq", "contains" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/members", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "role": { "type": "string" }, "roleKey": { "type": "string" }, "status": { "type": "string" }, "joinedAt": { "type": "string", "nullable": true } }, "required": [ "id", "userId", "email", "name", "avatarUrl", "role", "roleKey", "status", "joinedAt" ] } } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/newsjacking/settings": { "get": { "operationId": "get_v1_orgs_orgId_newsjacking_settings", "summary": "Get newsjacking autopilot settings", "description": "Whether the newsjacking autopilot is on, its daily draft cap, and the story behind the last draft it made.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Whether the newsjacking autopilot is on, its daily draft cap, and the story behind the last draft it made.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxDraftsPerDay": { "type": "integer" }, "lastDraftAt": { "type": "string", "nullable": true }, "lastStoryTitle": { "type": "string", "nullable": true } }, "required": [ "enabled", "maxDraftsPerDay", "lastDraftAt", "lastStoryTitle" ] } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "put_v1_orgs_orgId_newsjacking_settings", "summary": "Update newsjacking autopilot settings", "description": "Turns the newsjacking autopilot on or off and sets how many drafts it may make a day (1-3). Drafts land in Review; nothing posts without approval.", "tags": [ "marketing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxDraftsPerDay": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Turns the newsjacking autopilot on or off and sets how many drafts it may make a day (1-3). Drafts land in Review; nothing posts without approval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxDraftsPerDay": { "type": "integer" }, "lastDraftAt": { "type": "string", "nullable": true }, "lastStoryTitle": { "type": "string", "nullable": true } }, "required": [ "enabled", "maxDraftsPerDay", "lastDraftAt", "lastStoryTitle" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications/{notificationId}/dismiss": { "post": { "operationId": "post_v1_orgs_orgId_notifications_notificationId_dismiss", "summary": "Dismiss a notification", "description": "Clears one notification from the authenticated member's inbox. This is not the same as marking it read.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Clears one notification from the authenticated member's inbox. This is not the same as marking it read.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dismissedAt": { "type": "string" } }, "required": [ "id", "dismissedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications/{notificationId}/read": { "post": { "operationId": "post_v1_orgs_orgId_notifications_notificationId_read", "summary": "Mark a notification as read", "description": "Marks one notification as read for the authenticated member.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "notificationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Marks one notification as read for the authenticated member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "readAt": { "type": "string" }, "status": { "const": "read", "type": "string" } }, "required": [ "id", "readAt", "status" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications/dismiss-all": { "post": { "operationId": "post_v1_orgs_orgId_notifications_dismiss_all", "summary": "Clear notifications", "description": "Dismisses every active notification for the authenticated member in this organization, so the inbox and bell menu are empty.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dismisses every active notification for the authenticated member in this organization, so the inbox and bell menu are empty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dismissedCount": { "type": "integer" } }, "required": [ "dismissedCount" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications": { "get": { "operationId": "get_v1_orgs_orgId_notifications", "summary": "List workspace notifications", "description": "Returns in-app notifications for the authenticated member in this organization, newest first. Dismissed notifications are omitted.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "unreadOnly", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns in-app notifications for the authenticated member in this organization, newest first. Dismissed notifications are omitted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid", "nullable": true }, "type": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string", "nullable": true }, "href": { "type": "string", "nullable": true }, "tier": { "type": "string", "enum": [ "action_required", "meaningful_win", "routine" ] }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email" ] } }, "status": { "type": "string", "enum": [ "pending", "sent", "failed", "read" ] }, "dedupeKey": { "type": "string" }, "readAt": { "type": "string", "nullable": true }, "dismissedAt": { "type": "string", "nullable": true }, "emailSentAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "orgId", "type", "title", "body", "href", "tier", "channels", "status", "dedupeKey", "readAt", "dismissedAt", "emailSentAt", "createdAt" ] } }, "total": { "type": "integer" }, "unreadCount": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [ "items", "total", "unreadCount", "page", "limit" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications/preferences": { "get": { "operationId": "get_v1_orgs_orgId_notifications_preferences", "summary": "Get notification preferences", "description": "Returns email/in-app preference toggles for the authenticated member.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns email/in-app preference toggles for the authenticated member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "orgId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "emailEnabled": { "type": "boolean" }, "inAppEnabled": { "type": "boolean" }, "actionRequiredEmail": { "type": "boolean" }, "meaningfulWinEmail": { "type": "boolean" }, "routineEmail": { "type": "boolean" }, "digestEnabled": { "type": "boolean" }, "approvalRemindersEmail": { "type": "boolean" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "orgId", "userId", "emailEnabled", "inAppEnabled", "actionRequiredEmail", "meaningfulWinEmail", "routineEmail", "digestEnabled", "approvalRemindersEmail", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "put_v1_orgs_orgId_notifications_preferences", "summary": "Update notification preferences", "description": "Updates email/in-app preference toggles for the authenticated member.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailEnabled": { "type": "boolean" }, "inAppEnabled": { "type": "boolean" }, "actionRequiredEmail": { "type": "boolean" }, "meaningfulWinEmail": { "type": "boolean" }, "routineEmail": { "type": "boolean" }, "digestEnabled": { "type": "boolean" }, "approvalRemindersEmail": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updates email/in-app preference toggles for the authenticated member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "orgId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "emailEnabled": { "type": "boolean" }, "inAppEnabled": { "type": "boolean" }, "actionRequiredEmail": { "type": "boolean" }, "meaningfulWinEmail": { "type": "boolean" }, "routineEmail": { "type": "boolean" }, "digestEnabled": { "type": "boolean" }, "approvalRemindersEmail": { "type": "boolean" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "orgId", "userId", "emailEnabled", "inAppEnabled", "actionRequiredEmail", "meaningfulWinEmail", "routineEmail", "digestEnabled", "approvalRemindersEmail", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/notifications/read-all": { "post": { "operationId": "post_v1_orgs_orgId_notifications_read_all", "summary": "Mark all notifications as read", "description": "Marks every unread notification for the authenticated member as read.", "tags": [ "notifications" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Marks every unread notification for the authenticated member as read.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "markedCount": { "type": "integer" } }, "required": [ "markedCount" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/onboarding/from-website": { "post": { "operationId": "post_v1_orgs_orgId_onboarding_from_website", "summary": "POST /v1/orgs/{orgId}/onboarding/from-website", "description": "One-call first-run setup from a public website URL (and optional notes): infers a brand profile, generates a draft content plan, and persists both. Does not confirm the brand or activate the plan. Visual kit candidates remain GET /v1/orgs/{orgId}/brand/kit/website.", "tags": [ "orgs", "branding", "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "websiteUrl" ] } } } }, "responses": { "200": { "description": "One-call first-run setup from a public website URL (and optional notes): infers a brand profile, generates a draft content plan, and persists both. Does not confirm the brand or activate the plan. Visual kit candidates remain GET /v1/orgs/{orgId}/brand/kit/website.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "brand": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "nullable": true }, "logoUrl": { "type": "string", "format": "uri", "nullable": true }, "primaryFont": { "type": "string", "nullable": true }, "secondaryFont": { "type": "string", "nullable": true }, "colorPalette": { "type": "array", "items": { "type": "string" } }, "backgroundColor": { "type": "string", "nullable": true }, "logoAsset": { "type": "object", "properties": { "assetId": { "type": "string" }, "contentType": { "type": "string" }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "sourceAssetId": { "type": "string", "nullable": true } }, "required": [ "assetId", "contentType", "width", "height" ], "nullable": true }, "kitUpdatedAt": { "type": "string", "nullable": true }, "tagline": { "type": "string", "nullable": true }, "mission": { "type": "string", "nullable": true }, "voice": { "type": "object", "properties": { "tone": { "type": "string" }, "personalityTraits": { "type": "array", "items": { "type": "string" } }, "writingGuidelines": { "type": "array", "items": { "type": "string" } }, "bannedPhrases": { "type": "array", "items": { "type": "string" } } }, "required": [ "tone", "personalityTraits", "writingGuidelines", "bannedPhrases" ] }, "businessOutline": { "type": "object", "properties": { "overview": { "type": "string" }, "productsOrServices": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "valueProposition": { "type": "string" }, "differentiators": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "productsOrServices", "targetAudience", "valueProposition", "differentiators" ] }, "brandType": { "type": "string", "enum": [ "personal", "business", "unknown" ] }, "identity": { "type": "string", "nullable": true }, "expertise": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } }, "opinions": { "type": "array", "items": { "type": "string" } }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "private", "restricted" ] } }, "required": [ "id", "text" ] } }, "knowledgeItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "claim", "fact", "opinion", "preference", "topic" ] }, "text": { "type": "string" }, "disclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "durability": { "type": "string", "enum": [ "durable", "time_sensitive" ] }, "provenance": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "user", "inferred", "imported", "learned" ] }, "sourceType": { "type": "string", "nullable": true }, "sourceUrl": { "type": "string", "nullable": true }, "sourceExternalId": { "type": "string", "nullable": true }, "fetchedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "userSupplied": { "type": "boolean" } }, "required": [ "origin" ] }, "confirmed": { "type": "boolean" } }, "required": [ "id", "kind", "text", "provenance" ] } }, "preferenceSignals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signal": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "edit", "reject", "explicit" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "occurrences": { "type": "integer" }, "lastSeenAt": { "type": "string" }, "promoted": { "type": "boolean" } }, "required": [ "id", "signal", "kind", "lastSeenAt" ] } }, "profileDisclosure": { "type": "string", "enum": [ "public", "private", "restricted" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "confirmedAt": { "type": "string", "nullable": true }, "lastInferredAt": { "type": "string", "nullable": true }, "lastRefreshedAt": { "type": "string", "nullable": true } } } }, "required": [ "websiteUrl", "logoUrl", "primaryFont", "secondaryFont", "colorPalette", "tagline", "mission", "voice", "businessOutline" ] }, "source": { "type": "string", "enum": [ "ai", "heuristic" ] } }, "required": [ "profile", "source" ] }, "strategy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "brand", "strategy" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/onboarding": { "get": { "operationId": "get_v1_orgs_orgId_onboarding", "summary": "GET /v1/orgs/{orgId}/onboarding", "description": "GET /v1/orgs/{orgId}/onboarding", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GET /v1/orgs/{orgId}/onboarding", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currentStep": { "type": "string", "enum": [ "brand", "social", "x_connection", "billing", "strategy", "first_content" ] }, "completed": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "brand", "social", "x_connection", "billing", "strategy", "first_content" ] }, "label": { "type": "string" }, "completed": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": [ "key", "label", "completed", "required" ] } }, "brandProfileDetected": { "type": "boolean" }, "brandConfirmed": { "type": "boolean" }, "socialConnected": { "type": "boolean" }, "xConnected": { "type": "boolean" }, "strategyReady": { "type": "boolean" }, "firstContentReady": { "type": "boolean" }, "paidTrialActive": { "type": "boolean" }, "subscriptionRequired": { "type": "boolean" } }, "required": [ "currentStep", "completed", "steps", "brandProfileDetected", "brandConfirmed", "socialConnected", "xConnected", "strategyReady", "firstContentReady", "paidTrialActive", "subscriptionRequired" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_onboarding", "summary": "PATCH /v1/orgs/{orgId}/onboarding", "description": "PATCH /v1/orgs/{orgId}/onboarding", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentStep": { "type": "string", "enum": [ "brand", "social", "x_connection", "billing", "strategy", "first_content" ] } } } } } }, "responses": { "200": { "description": "PATCH /v1/orgs/{orgId}/onboarding", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currentStep": { "type": "string", "enum": [ "brand", "social", "x_connection", "billing", "strategy", "first_content" ] }, "completed": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "brand", "social", "x_connection", "billing", "strategy", "first_content" ] }, "label": { "type": "string" }, "completed": { "type": "boolean" }, "required": { "type": "boolean" } }, "required": [ "key", "label", "completed", "required" ] } }, "brandProfileDetected": { "type": "boolean" }, "brandConfirmed": { "type": "boolean" }, "socialConnected": { "type": "boolean" }, "xConnected": { "type": "boolean" }, "strategyReady": { "type": "boolean" }, "firstContentReady": { "type": "boolean" }, "paidTrialActive": { "type": "boolean" }, "subscriptionRequired": { "type": "boolean" } }, "required": [ "currentStep", "completed", "steps", "brandProfileDetected", "brandConfirmed", "socialConnected", "xConnected", "strategyReady", "firstContentReady", "paidTrialActive", "subscriptionRequired" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy/confirm": { "post": { "operationId": "post_v1_orgs_orgId_strategy_confirm", "summary": "POST /v1/orgs/{orgId}/strategy/confirm", "description": "Confirm the active strategy (optionally applying edits).", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "object", "properties": { "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] } } } } } } } }, "responses": { "200": { "description": "Confirm the active strategy (optionally applying edits).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy/generate": { "post": { "operationId": "post_v1_orgs_orgId_strategy_generate", "summary": "POST /v1/orgs/{orgId}/strategy/generate", "description": "Generate an AI-proposed strategy from goal + brand context.", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string" }, "replaceActive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Generate an AI-proposed strategy from goal + brand context.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy": { "get": { "operationId": "get_v1_orgs_orgId_strategy", "summary": "GET /v1/orgs/{orgId}/strategy", "description": "Get the active workspace strategy (canonical operating plan).", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get the active workspace strategy (canonical operating plan).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ], "nullable": true } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_strategy", "summary": "PATCH /v1/orgs/{orgId}/strategy", "description": "Edit the active workspace strategy.", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] } } } } } }, "responses": { "200": { "description": "Edit the active workspace strategy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy/priorities/{priorityId}": { "patch": { "operationId": "patch_v1_orgs_orgId_strategy_priorities_priorityId", "summary": "PATCH /v1/orgs/{orgId}/strategy/priorities/{priorityId}", "description": "Update or expire a temporary strategy priority.", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "priorityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] } } } } } }, "responses": { "200": { "description": "Update or expire a temporary strategy priority.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy/priorities": { "post": { "operationId": "post_v1_orgs_orgId_strategy_priorities", "summary": "POST /v1/orgs/{orgId}/strategy/priorities", "description": "Add a time-bounded campaign priority to the active strategy.", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Add a time-bounded campaign priority to the active strategy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/strategy/recommendations/{recommendationId}": { "post": { "operationId": "post_v1_orgs_orgId_strategy_recommendations_recommendationId", "summary": "POST /v1/orgs/{orgId}/strategy/recommendations/{recommendationId}", "description": "Accept or reject a suggested strategy change.", "tags": [ "strategy" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recommendationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "accepted", "rejected" ] } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "Accept or reject a suggested strategy change.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "superseded" ] }, "sourceGoal": { "type": "string", "nullable": true }, "primaryObjective": { "type": "string" }, "targetAudience": { "type": "string" }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name" ] } }, "channelPriorities": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "postsPerWeek": { "type": "number" } }, "required": [ "platform" ] } }, "contentMix": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "educational", "opinion", "personal", "community", "promotional" ] }, "targetPercent": { "type": "number" } }, "required": [ "contentType", "targetPercent" ] } }, "positioningAngles": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "theme": { "type": "string" }, "rationale": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "exploring", "done", "dismissed" ] } }, "required": [ "id", "theme" ] } }, "priorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "startsAt": { "type": "string" }, "endsAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "text", "startsAt" ] } }, "guardrailNotes": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string" }, "rationale": { "type": "string" }, "proposedChange": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "summary", "createdAt" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "meta": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "nullable": true }, "confirmedAt": { "type": "string", "nullable": true }, "confirmedBy": { "type": "string", "format": "uuid", "nullable": true }, "lastEditedAt": { "type": "string", "nullable": true }, "lastSuggestedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "version", "status", "primaryObjective", "targetAudience", "pillars", "channelPriorities", "contentMix", "meta", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/thoughts/{thoughtId}/drafts": { "post": { "operationId": "post_v1_orgs_orgId_thoughts_thoughtId_drafts", "summary": "Draft posts from a thought", "description": "Writes X and LinkedIn posts from a saved thought in a proven viral format and the brand voice, optionally with an on-brand image or carousel, and puts them in Review as pending approval. Never schedules or publishes.", "tags": [ "thoughts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "thoughtId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platforms": { "type": "array", "items": { "type": "string", "enum": [ "x", "linkedin" ] } }, "visual": { "type": "string", "enum": [ "none", "image", "carousel" ] }, "guidance": { "type": "string" }, "aiBackground": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Writes X and LinkedIn posts from a saved thought in a proven viral format and the brand voice, optionally with an on-brand image or carousel, and puts them in Review as pending approval. Never schedules or publishes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "thought": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "draftGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lastDraftedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "text", "kind", "status", "source", "tags", "draftGroupIds", "lastDraftedAt", "createdAt", "updatedAt" ] }, "group": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "topic": { "type": "string", "nullable": true }, "objective": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "canceled" ] }, "timezone": { "type": "string" }, "scheduledFor": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "approvedBy": { "type": "string", "format": "uuid", "nullable": true }, "approvedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tagIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } }, "strategyId": { "type": "string", "format": "uuid", "nullable": true }, "strategyVersion": { "type": "integer", "nullable": true }, "pillarId": { "type": "string", "nullable": true }, "priorityId": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "opportunityId": { "type": "string", "nullable": true } }, "required": [ "id", "orgId", "title", "topic", "objective", "status", "timezone", "scheduledFor", "approvedBy", "approvedAt", "createdAt", "updatedAt" ] }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "groupId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "x", "linkedin", "tiktok", "reddit", "facebook", "instagram", "youtube", "bluesky", "threads" ] }, "socialAccountId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "scheduled", "publishing", "awaiting_platform", "published", "failed", "canceled" ] }, "scheduledForUtc": { "type": "string", "nullable": true }, "scheduleReason": { "type": "string", "nullable": true }, "contentText": { "type": "string" }, "media": { "type": "object", "additionalProperties": {}, "nullable": true }, "platformPayload": { "type": "object", "additionalProperties": {}, "nullable": true }, "publishedExternalId": { "type": "string", "nullable": true }, "publishedUrl": { "type": "string", "nullable": true }, "attemptCount": { "type": "number" }, "lastAttemptAt": { "type": "string", "nullable": true }, "nextRetryAt": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "approvals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "level": { "type": "string", "enum": [ "group", "post" ] }, "groupId": { "type": "string", "format": "uuid" }, "postId": { "type": "string", "format": "uuid", "nullable": true }, "approvedByUserId": { "type": "string", "format": "uuid" }, "approvedAt": { "type": "string" }, "action": { "type": "string", "enum": [ "submit_for_approval", "approved", "reapproved", "rejected" ] } }, "required": [ "id", "level", "groupId", "postId", "approvedByUserId", "approvedAt", "action" ] } } }, "required": [ "id", "orgId", "groupId", "platform", "socialAccountId", "status", "scheduledForUtc", "contentText", "media", "platformPayload", "publishedExternalId", "publishedUrl", "attemptCount", "lastAttemptAt", "nextRetryAt", "lastError", "idempotencyKey", "createdAt", "updatedAt" ] } }, "visual": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "carousel" ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "format": { "type": "string", "enum": [ "square", "portrait", "landscape", "link", "story", "pin", "x_header", "linkedin_banner" ] }, "page": { "type": "integer" } }, "required": [ "assetId", "url", "contentType", "sizeBytes", "width", "height", "format" ] } }, "documentUrl": { "type": "string", "format": "uri", "nullable": true } }, "required": [ "kind", "images", "documentUrl" ], "nullable": true }, "visualError": { "type": "string", "nullable": true }, "providerModel": { "type": "string" }, "creditsUsed": { "type": "number" }, "remainingCredits": { "type": "number" } }, "required": [ "thought", "group", "posts", "visual", "visualError", "providerModel", "creditsUsed", "remainingCredits" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/thoughts/{thoughtId}": { "patch": { "operationId": "patch_v1_orgs_orgId_thoughts_thoughtId", "summary": "Update a thought", "description": "Edits a saved thought, or archives it so it stops feeding content generation.", "tags": [ "thoughts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "thoughtId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Edits a saved thought, or archives it so it stops feeding content generation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "draftGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lastDraftedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "text", "kind", "status", "source", "tags", "draftGroupIds", "lastDraftedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_orgs_orgId_thoughts_thoughtId", "summary": "Delete a thought", "description": "Deletes a saved thought. Drafts already made from it are kept.", "tags": [ "thoughts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "thoughtId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletes a saved thought. Drafts already made from it are kept.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "draftGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lastDraftedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "text", "kind", "status", "source", "tags", "draftGroupIds", "lastDraftedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/thoughts": { "get": { "operationId": "get_v1_orgs_orgId_thoughts", "summary": "List saved thoughts", "description": "Lists the thoughts, tips and opinions saved for content, newest first. Archived ones are hidden unless asked for.", "tags": [ "thoughts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "new", "drafted", "archived", "all" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lists the thoughts, tips and opinions saved for content, newest first. Archived ones are hidden unless asked for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "draftGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lastDraftedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "text", "kind", "status", "source", "tags", "draftGroupIds", "lastDraftedAt", "createdAt", "updatedAt" ] } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "limit", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs_orgId_thoughts", "summary": "Save a thought", "description": "Saves a thought, tip or opinion for content. Active thoughts are taken into account whenever posts are generated.", "tags": [ "thoughts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "Saves a thought, tip or opinion for content. Active thoughts are taken into account whenever posts are generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "thought", "tip", "opinion", "story", "lesson" ] }, "status": { "type": "string", "enum": [ "new", "drafted", "archived" ] }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "draftGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lastDraftedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "orgId", "text", "kind", "status", "source", "tags", "draftGroupIds", "lastDraftedAt", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/timezone": { "get": { "operationId": "get_v1_orgs_orgId_timezone", "summary": "Get workspace timezone", "description": "Returns the persisted IANA timezone used for best-slot scheduling and coverage. Defaults to UTC until set.", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns the persisted IANA timezone used for best-slot scheduling and coverage. Defaults to UTC until set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "timezone": { "type": "string" }, "isSet": { "type": "boolean" } }, "required": [ "timezone", "isSet" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_orgs_orgId_timezone", "summary": "Update workspace timezone", "description": "Sets the workspace IANA timezone used for scheduling. Owner/admin only.", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone": { "type": "string" } }, "required": [ "timezone" ] } } } }, "responses": { "200": { "description": "Sets the workspace IANA timezone used for scheduling. Owner/admin only.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "timezone": { "type": "string" }, "isSet": { "type": "boolean" } }, "required": [ "timezone", "isSet" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs/{orgId}/usage": { "get": { "operationId": "get_v1_orgs_orgId_usage", "summary": "Get this month's plan usage", "description": "Usage credits, storage, workspaces and seats used this billing month against the plan's allowances. Credits are shared by every workspace on the plan; 1 credit is 1 cent of AI, research, X and video delivery cost.", "tags": [ "billing" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "orgId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Usage credits, storage, workspaces and seats used this billing month against the plan's allowances. Credits are shared by every workspace on the plan; 1 credit is 1 cent of AI, research, X and video delivery cost.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "planKey": { "type": "string" }, "planName": { "type": "string", "nullable": true }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "state": { "type": "string", "enum": [ "ok", "nearly_out", "out" ] }, "credits": { "type": "object", "properties": { "included": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number" }, "usedByThisWorkspace": { "type": "number" }, "byCategory": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "label": { "type": "string" }, "credits": { "type": "number" } }, "required": [ "category", "label", "credits" ] } } }, "required": [ "included", "used", "remaining", "usedByThisWorkspace", "byCategory" ] }, "storage": { "type": "object", "properties": { "usedBytes": { "type": "number" }, "limitBytes": { "type": "number" }, "maxVideoUploadBytes": { "type": "number" } }, "required": [ "usedBytes", "limitBytes", "maxVideoUploadBytes" ] }, "workspaces": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "used", "limit" ] }, "seats": { "type": "object", "properties": { "used": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "used", "limit" ] } }, "required": [ "planKey", "planName", "periodStart", "periodEnd", "state", "credits", "storage", "workspaces", "seats" ] } }, "required": [ "data" ] } } } } } } }, "/v1/orgs": { "get": { "operationId": "get_v1_orgs", "summary": "GET /v1/orgs", "description": "GET /v1/orgs", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "slug", "status" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "eq", "contains" ] }, "slug": { "type": "string", "enum": [ "eq", "contains" ] }, "status": { "type": "string", "enum": [ "eq", "in" ] } } } } ], "responses": { "200": { "description": "GET /v1/orgs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "avatarUrl": { "type": "string", "nullable": true }, "role": { "type": "string" }, "roleName": { "type": "string" } }, "required": [ "id", "slug", "name", "status", "avatarUrl", "role", "roleName" ] } } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_orgs", "summary": "POST /v1/orgs", "description": "POST /v1/orgs", "tags": [ "orgs" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "name", "slug" ] } } } }, "responses": { "201": { "description": "POST /v1/orgs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "avatarUrl": { "type": "string", "nullable": true }, "ownerId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "id", "slug", "name", "status", "avatarUrl", "ownerId", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/public/pricing": { "get": { "operationId": "get_v1_public_pricing", "summary": "GET /v1/public/pricing", "description": "GET /v1/public/pricing", "tags": [ "public" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sortOrder", "name", "key", "monthlyPrice" ] } }, { "name": "sortDir", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "isActive": { "type": "string" } } } }, { "name": "filterOp", "in": "query", "required": false, "schema": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "eq", "contains" ] }, "key": { "type": "string", "enum": [ "eq", "contains" ] }, "isActive": { "type": "string", "enum": [ "eq" ] } } } }, { "name": "x-forwarded-for", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "GET /v1/public/pricing", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/public/waitlist": { "post": { "operationId": "post_v1_public_waitlist", "summary": "Join the waitlist", "description": "Adds an email, and optionally an X handle, to the AdVentur.ai waitlist. Joining again with the same email changes nothing.", "tags": [ "public" ], "parameters": [ { "name": "x-forwarded-for", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "xHandle": { "type": "string" }, "source": { "type": "string" }, "utmSource": {}, "utmMedium": {}, "utmCampaign": {}, "website": { "type": "string" } }, "required": [ "email", "xHandle", "source", "utmSource", "utmMedium", "utmCampaign" ] } } } }, "responses": { "200": { "description": "Adds an email, and optionally an X handle, to the AdVentur.ai waitlist. Joining again with the same email changes nothing.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/users/me": { "get": { "operationId": "get_v1_users_me", "summary": "GET /v1/users/me", "description": "GET /v1/users/me", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "GET /v1/users/me", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "boolean", "nullable": true }, "name": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "activeOrgId": { "type": "string", "format": "uuid", "nullable": true }, "featureFlags": { "type": "array", "items": { "type": "string", "enum": [ "youtube_publishing", "tiktok_publishing", "reddit_publishing", "linkedin_pages", "threads_publishing" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "id", "email", "emailVerified", "name", "avatarUrl", "activeOrgId", "featureFlags", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } }, "patch": { "operationId": "patch_v1_users_me", "summary": "PATCH /v1/users/me", "description": "PATCH /v1/users/me", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "format": "uri", "nullable": true }, "activeOrgId": { "type": "string", "format": "uuid", "nullable": true }, "locale": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "PATCH /v1/users/me", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "emailVerified": { "type": "boolean", "nullable": true }, "name": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true }, "activeOrgId": { "type": "string", "format": "uuid", "nullable": true }, "featureFlags": { "type": "array", "items": { "type": "string", "enum": [ "youtube_publishing", "tiktok_publishing", "reddit_publishing", "linkedin_pages", "threads_publishing" ] } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "id", "email", "emailVerified", "name", "avatarUrl", "activeOrgId", "featureFlags", "createdAt", "updatedAt" ] } }, "required": [ "data" ] } } } } } } }, "/v1/users/me/profile-image": { "get": { "operationId": "get_v1_users_me_profile_image", "summary": "GET /v1/users/me/profile-image", "description": "GET /v1/users/me/profile-image", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "GET /v1/users/me/profile-image", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "url": { "type": "string" }, "expiresInSeconds": { "type": "number" } }, "required": [ "key", "url", "expiresInSeconds" ] } }, "required": [ "data" ] } } } } } }, "post": { "operationId": "post_v1_users_me_profile_image", "summary": "POST /v1/users/me/profile-image", "description": "POST /v1/users/me/profile-image", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "POST /v1/users/me/profile-image", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "avatarUrl": { "type": "string", "nullable": true }, "key": { "type": "string" } }, "required": [ "avatarUrl", "key" ] } }, "required": [ "data" ] } } } } } }, "delete": { "operationId": "delete_v1_users_me_profile_image", "summary": "DELETE /v1/users/me/profile-image", "description": "DELETE /v1/users/me/profile-image", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "DELETE /v1/users/me/profile-image", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/users/me/profile-image/upload-url": { "post": { "operationId": "post_v1_users_me_profile_image_upload_url", "summary": "POST /v1/users/me/profile-image/upload-url", "description": "POST /v1/users/me/profile-image/upload-url", "tags": [ "users" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string" } }, "required": [ "contentType" ] } } } }, "responses": { "200": { "description": "POST /v1/users/me/profile-image/upload-url", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploadUrl": { "type": "string" }, "key": { "type": "string" }, "assetUrl": { "type": "string" }, "expiresInSeconds": { "type": "number" }, "method": { "const": "PUT", "type": "string" }, "requiredHeaders": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "uploadUrl", "key", "assetUrl", "expiresInSeconds", "method", "requiredHeaders" ] } }, "required": [ "data" ] } } } } } } } } }