{ "openapi": "3.1.0", "info": { "title": "Citedy Agent API", "version": "1.0.0", "description": "Public contract for Citedy agent integrations. This contract reflects the current /api/agent surface without changing runtime behavior.", "contact": { "name": "Citedy Support", "url": "https://www.citedy.com" }, "license": { "name": "Proprietary", "url": "https://www.citedy.com" } }, "servers": [ { "url": "https://www.citedy.com" } ], "tags": [ { "name": "Health", "description": "Platform and dependency health" }, { "name": "Registration", "description": "Agent onboarding and approval" }, { "name": "Agent", "description": "Agent identity and key lifecycle" }, { "name": "Scout", "description": "Trend scouting endpoints" }, { "name": "Gaps", "description": "Content gap analysis" }, { "name": "Autopilot", "description": "Article generation and retrieval" }, { "name": "Articles", "description": "Queued article generation job polling" }, { "name": "Adaptations", "description": "Social adaptation generation" }, { "name": "Sessions", "description": "Autopilot recurring sessions" }, { "name": "Lead Magnets", "description": "Lead magnet generation and state" }, { "name": "Warm Leads", "description": "Warm-lead report generation and export" }, { "name": "Ingest", "description": "Content ingestion jobs" }, { "name": "Competitors", "description": "Competitor discovery and analysis" }, { "name": "Personas", "description": "Writing persona catalog" }, { "name": "Webhooks", "description": "Webhook endpoint registration and delivery logs" }, { "name": "Publishing", "description": "Social publishing, scheduling and cancellation" }, { "name": "Schedule", "description": "Content schedule timeline and gap analysis" }, { "name": "Settings", "description": "Agent preferences and configuration" }, { "name": "Scan", "description": "Experimental trend scanning (xAI Grok)" }, { "name": "Status", "description": "Operational readiness and actionable onboarding status" }, { "name": "Products", "description": "Product knowledge base document management" }, { "name": "Shorts", "description": "Short-form video generation and polling" }, { "name": "SEO Tools", "description": "Agent-authenticated SEO diagnostics tools exposed via MCP seo.* namespace." }, { "name": "GSC", "description": "Google Search Console integration and reporting" } ], "paths": { "/api/agent/health": { "get": { "tags": ["Health"], "operationId": "getAgentPlatformHealth", "summary": "Health check", "security": [], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Degraded or unhealthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResponse" } } } } } } }, "/api/agent/register": { "post": { "tags": ["Registration"], "operationId": "registerAgentPending", "summary": "Create pending agent registration", "description": "Flow A: creates a pending registration and returns approval URL. No API key is returned here.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentRequest" } } } }, "responses": { "200": { "description": "Pending registration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterAgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/pending/{id}": { "get": { "tags": ["Registration"], "operationId": "getPendingAgentStatus", "summary": "Check pending registration status", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:[a-fA-F0-9]{16}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } } ], "responses": { "200": { "description": "Status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingRegistrationStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "Pending registration dependency temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryableErrorResponse" } } } } } } }, "/api/agent/approve": { "post": { "tags": ["Registration"], "operationId": "approvePendingAgent", "summary": "Approve pending registration", "description": "Flow A step 2. Requires authenticated tenant owner session (dashboard auth), not agent API key.", "security": [ { "TenantSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAgentRequest" } } } }, "responses": { "200": { "description": "Approved and API key issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "description": "Pending registration expired or not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/me": { "get": { "tags": ["Agent"], "operationId": "getAgentContext", "summary": "Get agent info, balance and limits", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Agent context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/rotate-key": { "post": { "tags": ["Agent"], "operationId": "rotateAgentKey", "summary": "Rotate current agent API key", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "New key generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/scout/x": { "post": { "tags": ["Scout"], "operationId": "runXScout", "summary": "Run X/Twitter scout", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutXRequest" } } } }, "responses": { "200": { "description": "Scout dispatched (async). Poll GET /api/agent/scout/x/{runId} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutXResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/scout/reddit": { "post": { "tags": ["Scout"], "operationId": "runRedditScout", "summary": "Run Reddit scout", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutRedditRequest" } } } }, "responses": { "200": { "description": "Scout dispatched (async). Poll GET /api/agent/scout/reddit/{runId} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutRedditResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/scout/reddit/{runId}": { "get": { "tags": ["Scout"], "operationId": "getRedditScoutResult", "summary": "Poll Reddit scout result", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scout poll result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutPollResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/scout/x/{runId}": { "get": { "tags": ["Scout"], "operationId": "getXScoutResult", "summary": "Poll X scout result", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scout poll result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoutPollResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/gaps": { "get": { "tags": ["Gaps"], "operationId": "listContentGaps", "summary": "List content gaps", "description": "List saved content gaps. Optional `favorite_id` scopes results to a product/identity (hybrid filter keeps legacy NULL gaps visible via domain-match).", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "in": "query", "name": "favorite_id", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter to gaps tagged with this favorite. Owner-checked against tenant — cross-tenant favorites return 403. The legacy-NULL fallback (rows where favorite_id IS NULL but domain matches) is appended only when the favorite's domain normalizes successfully; if normalization fails, the fallback is dropped and missing legacy gaps may indicate an invalid favorite domain rather than a data bug." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Max items to return." } ], "responses": { "200": { "description": "List of gaps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGapsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/gaps/generate": { "post": { "tags": ["Gaps"], "operationId": "generateContentGaps", "summary": "Generate content gaps", "description": "Generate content gaps from competitor URLs. Optional `favorite_id` scopes the resulting gaps to a product/identity and uses `ai_favorites.domain` as the analysis target instead of the tenant blog domain. Cross-tenant `favorite_id` is rejected with 403 before credits are charged.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateGapsRequest" } } } }, "responses": { "200": { "description": "Gaps generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateGapsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/autopilot": { "post": { "tags": ["Autopilot"], "operationId": "generateAutopilotArticle", "summary": "Generate article", "description": "Generate an article from a topic or source URLs. Returns status 'publishing' when auto_publish is true (default) or 'generated' when auto_publish is false (draft mode). The final 'published' status is reflected in GET /api/agent/articles/{id} after the publish pipeline completes.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopilotRequest" } } } }, "responses": { "200": { "description": "Article generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopilotResponse" } } } }, "202": { "description": "Article generation accepted for async processing. Poll GET /api/agent/articles/{id} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutopilotQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/articles": { "get": { "tags": ["Autopilot"], "operationId": "listAgentArticles", "summary": "List articles", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Articles page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListArticlesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/adapt": { "post": { "tags": ["Adaptations"], "operationId": "generateSocialAdaptations", "summary": "Generate social adaptations", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdaptRequest" } } } }, "responses": { "200": { "description": "Adaptations generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdaptResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/session": { "post": { "tags": ["Sessions"], "operationId": "createAutopilotSession", "summary": "Create and start autopilot session", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "200": { "description": "Session started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/lead-magnets": { "post": { "tags": ["Lead Magnets"], "operationId": "createLeadMagnet", "summary": "Generate lead magnet", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadMagnetRequest" } } } }, "responses": { "200": { "description": "Generation queued. Poll GET /api/agent/lead-magnets/{id} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadMagnetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Feature not implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Failed to queue generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/lead-magnets/{id}": { "get": { "tags": ["Lead Magnets"], "operationId": "getLeadMagnet", "summary": "Get lead magnet status/details", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lead magnet state", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LeadMagnetGeneratingResponse" }, { "$ref": "#/components/schemas/LeadMagnetCompletedResponse" } ], "discriminator": { "propertyName": "status", "mapping": { "generating": "#/components/schemas/LeadMagnetGeneratingResponse", "completed": "#/components/schemas/LeadMagnetCompletedResponse", "published": "#/components/schemas/LeadMagnetCompletedResponse", "archived": "#/components/schemas/LeadMagnetCompletedResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": ["Lead Magnets"], "operationId": "updateLeadMagnetStatus", "summary": "Publish or archive lead magnet", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadMagnetRequest" } } } }, "responses": { "200": { "description": "Lead magnet updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadMagnetCompletedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/lead-magnets/{id}/wait": { "get": { "tags": ["Lead Magnets"], "operationId": "waitForLeadMagnet", "summary": "Long-poll wait for lead magnet completion", "description": "Hangs open up to 25s polling for generation completion. Call immediately after POST /lead-magnets. Returns full result when ready, progress on timeout, or error on failure.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Lead magnet run ID from POST response" }, { "name": "timeout", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 25 }, "description": "Max wait seconds (clamped 1-25)" } ], "responses": { "200": { "description": "Lead magnet result, progress, or failure" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/agent/citedy-warm-lead": { "post": { "tags": ["Warm Leads"], "operationId": "createCitedyWarmLeadRun", "summary": "Start a Citedy warm-lead report", "description": "Creates one tenant-scoped warm-lead run for one company domain. Accepted new runs charge exactly 40 Citedy credits. Poll GET /api/agent/citedy-warm-lead/{runId} for status and result.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWarmLeadRunRequest" } } } }, "responses": { "200": { "description": "Existing idempotent warm-lead run returned without a new credit charge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWarmLeadRunResponse" } } } }, "202": { "description": "Warm-lead run accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWarmLeadRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/citedy-warm-lead/{runId}": { "get": { "tags": ["Warm Leads"], "operationId": "getCitedyWarmLeadRun", "summary": "Get a Citedy warm-lead run", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Warm-lead run state and canonical JSON result when available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WarmLeadRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/citedy-warm-lead/{runId}/export": { "get": { "tags": ["Warm Leads"], "operationId": "exportCitedyWarmLeadRun", "summary": "Export a Citedy warm-lead report", "description": "Downloads an export projection of the canonical JSON result. Supported formats: JSON, CSV, and Excel .xlsx.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["json", "csv", "xlsx"], "default": "json" } } ], "responses": { "200": { "description": "Warm-lead export file", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Canonical warm-lead JSON result object." } }, "text/csv": { "schema": { "type": "string", "description": "CSV export text." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary", "description": "Excel .xlsx binary export." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/ingest": { "get": { "tags": ["Ingest"], "operationId": "listIngestJobs", "summary": "List ingestion jobs", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["processing", "completed", "failed"] } } ], "responses": { "200": { "description": "Paginated list of ingestion jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Ingest"], "operationId": "createIngestJob", "summary": "Create ingestion job", "description": "Returns 202 for new jobs or 200 for cached results (dedup hit).", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestCreateRequest" } } } }, "responses": { "200": { "description": "Cached result (dedup hit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestCachedResponse" } } } }, "202": { "description": "New job created and processing. Poll GET /api/agent/ingest/{id} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/ingest/{id}": { "get": { "tags": ["Ingest"], "operationId": "getIngestJob", "summary": "Poll ingestion job status", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status (processing, completed, or failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestJobStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/ingest/{id}/content": { "get": { "tags": ["Ingest"], "operationId": "getIngestJobContent", "summary": "Download raw ingested content", "description": "Streams the raw content file from R2 storage. Primary response is a binary octet-stream; some content types may return JSON.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Raw content stream from R2 storage", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "$ref": "#/components/responses/BadGateway" } } } }, "/api/agent/ingest/batch": { "post": { "tags": ["Ingest"], "operationId": "createIngestBatch", "summary": "Batch create ingestion jobs", "description": "Returns 202 if at least one URL succeeded, 400 if all failed.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestBatchRequest" } } } }, "responses": { "202": { "description": "Batch accepted (partial or full success)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestBatchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/competitors/discover": { "post": { "tags": ["Competitors"], "operationId": "discoverCompetitors", "summary": "Discover competitors by keywords", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorDiscoverRequest" } } } }, "responses": { "200": { "description": "Competitors discovered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorDiscoverResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/competitors/scout": { "post": { "tags": ["Competitors"], "operationId": "scoutCompetitor", "summary": "Analyze a competitor domain", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorScoutRequest" } } } }, "responses": { "200": { "description": "Competitor analysis complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorScoutResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/webhooks": { "post": { "tags": ["Webhooks"], "operationId": "registerWebhookEndpoint", "summary": "Register webhook endpoint", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegisterRequest" } } } }, "responses": { "201": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegisterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "tags": ["Webhooks"], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Webhook endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/webhooks/deliveries": { "get": { "tags": ["Webhooks"], "operationId": "listWebhookDeliveries", "summary": "List webhook delivery history", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/WebhookDeliveryStatus" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Delivery history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/webhooks/{id}": { "delete": { "tags": ["Webhooks"], "operationId": "deleteWebhookEndpoint", "summary": "Delete webhook endpoint", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook endpoint deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/personas": { "get": { "tags": ["Personas"], "operationId": "listPersonas", "summary": "List available personas", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Personas list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonasResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/publish": { "post": { "tags": ["Publishing"], "operationId": "publishSocialAdaptation", "summary": "Publish, schedule, cancel, or direct-publish (as-is) social content", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } } }, "responses": { "200": { "description": "Publish action completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Platform publishing locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Adaptation not in publishable state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/schedule": { "get": { "tags": ["Schedule"], "operationId": "getScheduleTimeline", "summary": "Get scheduled content timeline", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date (default: today)" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date (default: today + 14 days)" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["all", "article", "post", "social"], "default": "all" } } ], "responses": { "200": { "description": "Schedule items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/schedule/gaps": { "get": { "tags": ["Schedule"], "operationId": "getScheduleGaps", "summary": "Identify days with fewer posts than target", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 } }, { "name": "timezone", "in": "query", "schema": { "type": "string" }, "description": "IANA timezone (defaults to agent setting)" } ], "responses": { "200": { "description": "Schedule gaps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleGapsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/schedule/suggest": { "get": { "tags": ["Schedule"], "operationId": "suggestTimeSlots", "summary": "Get recommended posting time slots", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Suggested slots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleSuggestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/settings": { "get": { "tags": ["Settings"], "operationId": "getAgentSettings", "summary": "Get agent preferences and configuration", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Current settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "tags": ["Settings"], "operationId": "updateAgentSettings", "summary": "Update agent preferences (partial update)", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentSettingsRequest" } } } }, "responses": { "200": { "description": "Updated settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSettingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/post": { "post": { "tags": ["Autopilot"], "operationId": "createMicroPost", "summary": "Create micro-content post with social adaptations", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostRequest" } } } }, "responses": { "200": { "description": "Post created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/scan": { "post": { "tags": ["Scan"], "operationId": "scanTrends", "summary": "Scan trends via xAI Grok (experimental)", "description": "Search X/Twitter, web, and HackerNews for trending content. Credit cost: fast=2, deep=4, ultra=6.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanRequest" } } } }, "responses": { "200": { "description": "Scan results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/image-style": { "put": { "tags": ["Settings"], "operationId": "updateImageStyle", "summary": "Set illustration style preset", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImageStyleRequest" } } } }, "responses": { "200": { "description": "Style updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImageStyleResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/status": { "get": { "tags": ["Status"], "operationId": "getAgentStatus", "summary": "Get operational agent status", "description": "Returns actionable status snapshot for credits, social connections, schedule, knowledge base and content readiness.", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Status snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/products": { "post": { "tags": ["Products"], "operationId": "createProductDocument", "summary": "Upload product knowledge document", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateRequest" } } } }, "responses": { "201": { "description": "Document uploaded and embedded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "422": { "description": "Tenant document limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "tags": ["Products"], "operationId": "listProductDocuments", "summary": "List product knowledge documents", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Product knowledge documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/products/{id}": { "delete": { "tags": ["Products"], "operationId": "deleteProductDocument", "summary": "Delete product knowledge document by ID", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/products/search": { "post": { "tags": ["Products"], "operationId": "searchProductKnowledge", "summary": "Search product knowledge documents", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts": { "post": { "tags": ["Shorts"], "operationId": "generateShortsVideo", "summary": "Generate short-form video", "description": "Starts short-form video generation and returns immediate processing status for polling.", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsGenerateRequest" } } } }, "responses": { "200": { "description": "Generation accepted. Poll GET /api/agent/shorts/{id} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsGenerateAcceptedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts/{id}": { "get": { "tags": ["Shorts"], "operationId": "getShortsVideoStatus", "summary": "Get shorts generation status by ID", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generation status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts/script": { "post": { "tags": ["Shorts"], "operationId": "generateShortsScript", "summary": "Generate shorts script", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsScriptRequest" } } } }, "responses": { "200": { "description": "Script generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsScriptResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts/avatar": { "post": { "tags": ["Shorts"], "operationId": "generateShortsAvatar", "summary": "Generate shorts avatar", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsAvatarRequest" } } } }, "responses": { "200": { "description": "Avatar generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsAvatarResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts/merge": { "post": { "tags": ["Shorts"], "operationId": "mergeShortsVideo", "summary": "Merge shorts videos and add subtitles", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsMergeRequest" } } } }, "responses": { "200": { "description": "Merge completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsMergeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/shorts/publish": { "post": { "tags": ["Shorts"], "operationId": "publishShortVideo", "summary": "Publish short video to YouTube Shorts, Instagram Reels, and/or TikTok", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsPublishRequest" } } } }, "responses": { "200": { "description": "Publish completed (check per-platform results)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortsPublishResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/tools": { "get": { "tags": ["SEO Tools"], "summary": "List available agent tools", "operationId": "agentToolsManifest", "security": [ { "AgentApiKey": [] } ], "responses": { "200": { "description": "Available tool manifest", "content": { "application/json": { "schema": { "type": "object", "required": ["count", "tools"], "properties": { "count": { "type": "integer", "minimum": 0 }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "method", "path", "required_fields", "sample_payload" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] }, "path": { "type": "string" }, "required_fields": { "type": "array", "items": { "type": "string" } }, "sample_payload": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/agent/tools/meta-tags": { "post": { "tags": ["SEO Tools"], "summary": "Analyze page meta tags", "operationId": "seoMetaTagsCheck", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/headings": { "post": { "tags": ["SEO Tools"], "summary": "Analyze heading hierarchy", "operationId": "seoHeadingsCheck", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/links": { "post": { "tags": ["SEO Tools"], "summary": "Analyze page links", "operationId": "seoLinksAnalyze", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/internal-links": { "post": { "tags": ["SEO Tools"], "summary": "Plan internal links from page + targets", "operationId": "seoInternalLinksPlan", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoInternalLinksRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/og-preview": { "post": { "tags": ["SEO Tools"], "summary": "Extract Open Graph/Twitter preview metadata", "operationId": "seoOgPreview", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/schema-validate": { "post": { "tags": ["SEO Tools"], "summary": "Validate page JSON-LD schema markup", "operationId": "seoSchemaValidate", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/robots": { "post": { "tags": ["SEO Tools"], "summary": "Analyze robots.txt directives", "operationId": "seoRobotsCheck", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/sitemap": { "post": { "tags": ["SEO Tools"], "summary": "Check sitemap availability and robots.txt hints", "operationId": "seoSitemapCheck", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolUrlRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/og-image": { "post": { "tags": ["SEO Tools"], "summary": "Generate branded Open Graph image", "operationId": "seoOgImageGenerate", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoOgImageRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoToolSuccessResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "409": { "description": "Missing logo or settings conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Logo payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/brand-scan": { "post": { "tags": ["SEO Tools"], "summary": "Start async AI brand visibility scan", "operationId": "brandScanStart", "security": [ { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandScanStartRequest" } } } }, "responses": { "200": { "description": "Scan accepted. Poll GET /api/agent/tools/brand-scan/{id} with the same Authorization: Bearer header for status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandScanStartResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "409": { "description": "Another scan is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/tools/brand-scan/{id}": { "get": { "tags": ["SEO Tools"], "summary": "Get async brand scan status/result", "operationId": "brandScanGet", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scan status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandScanStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/agent/articles/{id}": { "get": { "tags": ["Articles"], "operationId": "getArticleJobStatus", "summary": "Get queued article generation status or result by ID", "description": "Poll for the status of a queued article generation job. Returns processing status while the article is being generated, or the final result (success/failure) once complete.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The job ID returned by POST /api/agent/autopilot when wait_for_completion is false" } ], "responses": { "200": { "description": "Job status or completed article result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleJobStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": ["Articles"], "operationId": "unpublishArticle", "summary": "Unpublish an article (revert to draft)", "description": "Set article status back to 'generated'. The article remains in the system but is removed from the public blog. Only articles with status 'published' can be unpublished; attempting to unpublish an article in any other status returns 400.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["unpublish"] } } } } } }, "responses": { "200": { "description": "Article unpublished successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "article_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["generated"] }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Article is not in the required state for this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Cannot unpublish article with status \"generated\"" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": ["Articles"], "operationId": "deleteArticle", "summary": "Permanently delete an article", "description": "Permanently delete an article regardless of its current status (generated, published, failed, etc.). Performs cascading cleanup: removes the article database record and associated storage files (illustrations, voice-overs) on a best-effort basis. This operation is permanent and cannot be undone.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article ID" } ], "responses": { "200": { "description": "Article deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "article_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["deleted"] }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/articles/{id}/publish": { "post": { "tags": ["Articles"], "operationId": "publishArticle", "summary": "Publish a draft article", "description": "Trigger the publish pipeline for a draft article (status=generated). The article will be available on the public blog shortly after.", "security": [ { "AgentApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Article ID" } ], "responses": { "200": { "description": "Publish pipeline triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "article_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["publishing", "published"] }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Article is not in the required state for this operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Cannot publish article with status \"failed\"" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/gsc/report": { "get": { "tags": ["GSC"], "operationId": "getGscReport", "summary": "Get GSC performance report", "description": "Returns Google Search Console performance report with clicks, impressions, CTR, positions, top queries, top pages, movers, opportunities, and article suggestions. Returns connect URL if GSC is not linked. Free (0 credits).", "security": [{ "AgentApiKey": [] }], "parameters": [ { "name": "force_refresh", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Force fresh GSC data fetch instead of cached morning report" } ], "responses": { "200": { "description": "GSC report (connected) or connect URL (not connected)", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "connected": { "type": "boolean", "enum": [true] }, "cached": { "type": "boolean" }, "reportDate": { "type": "string", "format": "date" }, "gscProperty": { "type": "string" }, "rangeDays": { "type": "integer" }, "summary": { "type": "object", "properties": { "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" }, "clicksChangePct": { "type": ["number", "null"] }, "impressionsChangePct": { "type": ["number", "null"] } } }, "topQueries": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } } } }, "topPages": { "type": "array", "items": { "type": "object", "properties": { "page": { "type": "string" }, "clicks": { "type": "integer" }, "impressions": { "type": "integer" }, "ctr": { "type": "number" }, "position": { "type": "number" } } } }, "movers": { "type": "object", "properties": { "gainers": { "type": "array", "items": { "type": "object" } }, "losers": { "type": "array", "items": { "type": "object" } } } }, "opportunities": { "type": "array", "items": { "type": "object" } }, "articleSuggestions": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "reason": { "type": "string" }, "impressions": { "type": "integer" }, "position": { "type": "number" }, "opportunityScore": { "type": "number" }, "workflow": { "type": "string" } } } } }, "required": ["connected", "reportDate", "summary"] }, { "type": "object", "properties": { "connected": { "type": "boolean", "enum": [false] }, "connect_url": { "type": "string", "format": "uri" }, "message": { "type": "string" } }, "required": ["connected", "connect_url", "message"] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "AgentApiKey": { "type": "http", "scheme": "bearer", "description": "Bearer citedy_agent_* key" }, "TenantSession": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "Supabase dashboard session cookie" } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "PaymentRequired": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredResponse" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadGateway": { "description": "Bad gateway -- upstream storage fetch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": ["error"], "additionalProperties": true }, "RateLimitErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "retry_after": { "type": "integer" } }, "required": ["retry_after"] } ] }, "RetryableErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "retry_after": { "type": "integer" } }, "required": ["retry_after"] } ] }, "PaymentRequiredResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "credits_required": { "type": "number" }, "breakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "topup": { "type": "object", "description": "Recommended credit top-up package with billing URL", "properties": { "recommended_package_credits": { "type": "integer", "description": "Credits in the recommended package" }, "recommended_package_price_usd": { "type": "number", "description": "Price of the recommended package in USD" }, "topup_url": { "type": "string", "format": "uri", "description": "URL to billing page with package pre-selected" } }, "required": [ "recommended_package_credits", "recommended_package_price_usd", "topup_url" ] } }, "required": ["credits_required", "topup"], "additionalProperties": true } ] }, "HealthCheckResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": ["healthy", "degraded", "unhealthy"] }, "checks": { "type": "object", "properties": { "redis": { "type": "boolean" }, "supabase": { "type": "boolean" } }, "required": ["redis", "supabase"] }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } }, "required": ["status", "checks", "timestamp"] }, "RegisterAgentRequest": { "type": "object", "properties": { "agent_name": { "type": "string", "minLength": 3, "maxLength": 50 }, "description": { "type": "string", "maxLength": 500 } }, "required": ["agent_name"], "additionalProperties": false }, "RegisterAgentResponse": { "type": "object", "properties": { "pending_id": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "status": { "type": "string", "enum": ["awaiting_approval"] } }, "required": ["pending_id", "approval_url"], "additionalProperties": false }, "PendingRegistrationStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": ["awaiting_approval", "expired"] }, "agent_name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" } }, "required": ["status"], "additionalProperties": false }, "ApproveAgentRequest": { "type": "object", "properties": { "pending_id": { "type": "string" } }, "required": ["pending_id"], "additionalProperties": false }, "ApproveAgentResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_api_key": { "type": "string", "pattern": "^citedy_agent_" }, "status": { "type": "string", "enum": ["active"] } }, "required": ["agent_id", "agent_api_key", "status"], "additionalProperties": false }, "AgentMeResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_name": { "type": "string" }, "status": { "type": "string" }, "api_key_prefix": { "type": "string" }, "last_activity_at": { "type": ["string", "null"], "format": "date-time" }, "total_credits_used": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "blog_url": { "type": ["string", "null"], "format": "uri" }, "tenant_balance": { "type": "object", "properties": { "credits": { "type": "number" }, "status": { "type": "string", "enum": ["healthy", "low", "empty"] } }, "required": ["credits", "status"] }, "rate_limits": { "type": "object", "additionalProperties": { "type": "object", "properties": { "remaining": { "type": "integer" }, "resetAt": { "type": "string", "format": "date-time" } }, "required": ["remaining", "resetAt"] } }, "referral": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": ["code", "url"] }, "connected_platforms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": ["string", "null"], "format": "uuid", "description": "Legacy primary active social account UUID. Equals the first accounts entry ordered by ID." }, "platform": { "type": "string" }, "connected": { "type": "boolean" }, "account_name": { "type": ["string", "null"] }, "accounts": { "type": "array", "description": "All active social accounts for this platform, ordered by ID. Use an explicit account ID when publishing.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" } }, "required": ["id", "account_name"], "additionalProperties": false } } }, "required": [ "id", "platform", "connected", "account_name", "accounts" ] } }, "stats_url": { "type": ["string", "null"], "format": "uri" } }, "required": [ "agent_id", "agent_name", "status", "api_key_prefix", "total_credits_used", "created_at", "tenant_balance", "rate_limits", "connected_platforms" ], "additionalProperties": false }, "RotateKeyResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_api_key": { "type": "string", "pattern": "^citedy_agent_" }, "message": { "type": "string" } }, "required": ["agent_id", "agent_api_key", "message"], "additionalProperties": false }, "ScoutXRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "mode": { "type": "string", "enum": ["fast", "ultimate"], "default": "fast" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, "required": ["query"], "additionalProperties": false }, "ScoutRedditRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "subreddits": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "default": [] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, "required": ["query"], "additionalProperties": false }, "ScoutResponseBase": { "type": "object", "description": "Shared fields for all scout responses.", "properties": { "run_id": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "results": { "type": "object", "additionalProperties": true }, "credits_used": { "type": "number" }, "status": { "type": "string" } }, "required": ["run_id", "query", "credits_used"] }, "ScoutXResponse": { "allOf": [ { "$ref": "#/components/schemas/ScoutResponseBase" }, { "type": "object", "properties": { "mode": { "type": "string", "enum": ["fast", "ultimate"] } }, "required": ["mode"] } ] }, "ScoutRedditResponse": { "allOf": [ { "$ref": "#/components/schemas/ScoutResponseBase" }, { "type": "object", "properties": { "subreddits": { "type": "array", "items": { "type": "string" } } }, "required": ["subreddits"] } ] }, "ScoutPollResponse": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["processing", "completed", "failed"] }, "results": { "type": "object", "additionalProperties": true }, "error": { "type": "string" }, "mode": { "type": "string" } }, "required": ["run_id", "status"] }, "GapItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "gap_type": { "type": "string" }, "priority": { "type": "string" }, "opportunity_score": { "type": ["number", "null"] }, "status": { "type": "string" }, "description": { "type": ["string", "null"] }, "favorite_id": { "type": ["string", "null"], "format": "uuid", "description": "Favorite (product identity) ID this gap is scoped to, or null for legacy tenant-wide gaps." }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["title", "gap_type", "priority"], "additionalProperties": true }, "ListGapsResponse": { "type": "object", "properties": { "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/GapItem" } }, "total_gaps": { "type": "integer" }, "credits_used": { "type": "number" } }, "required": ["gaps", "total_gaps", "credits_used"], "additionalProperties": false }, "GenerateGapsRequest": { "type": "object", "properties": { "competitor_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 5 }, "favorite_id": { "type": "string", "format": "uuid", "description": "Optional favorite (product identity) ID from ai_favorites. Owner-checked against tenant; gaps are tagged and analysis domain is overridden to ai_favorites.domain." } }, "required": ["competitor_urls"], "additionalProperties": false }, "GenerateGapsResponse": { "type": "object", "properties": { "gaps_found": { "type": "integer" }, "gaps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "credits_used": { "type": "number" } }, "required": ["gaps_found", "gaps", "credits_used"], "additionalProperties": false }, "AutopilotRequestBase": { "type": "object", "properties": { "topic": { "type": "string", "minLength": 1, "maxLength": 500 }, "source_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 3 }, "language": { "type": "string", "default": "en" }, "size": { "type": "string", "enum": ["mini", "standard", "full", "pillar"], "default": "standard" }, "mode": { "type": "string", "enum": ["standard", "turbo"], "default": "standard" }, "enable_search": { "type": "boolean", "default": false }, "persona": { "type": "string", "maxLength": 100 }, "illustrations": { "type": "boolean", "default": false }, "audio": { "type": "boolean", "default": false }, "disable_competition": { "type": "boolean", "default": false }, "wait_for_completion": { "type": "boolean", "description": "Wait synchronously for article completion before returning. When false, returns 202 with a job ID for polling via GET /api/agent/articles/{id}.", "default": true }, "auto_publish": { "type": "boolean", "description": "Publish article immediately after generation. When false, article stays as draft (status=generated). Uses tenant setting when omitted." } }, "additionalProperties": false }, "AutopilotRequest": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/AutopilotRequestBase" }, { "required": ["topic"] } ] }, { "allOf": [ { "$ref": "#/components/schemas/AutopilotRequestBase" }, { "required": ["source_urls"] } ] } ] }, "AutopilotResponse": { "type": "object", "properties": { "article_id": { "type": ["string", "null"], "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "article_url": { "type": "string", "format": "uri", "description": "URL where the article will be accessible once published. For draft articles (auto_publish: false), this URL will return 404 until the article is published." }, "status": { "type": "string", "enum": ["publishing", "generated"], "description": "publishing — article generation complete, publish pipeline triggered (will be live within seconds). generated — draft article, not yet published (use article.publish to make it live)." }, "mode": { "type": "string" }, "word_count": { "type": "integer" }, "credits_used": { "type": "number" }, "estimated_total_credits": { "type": "number" }, "extensions": { "type": "object", "additionalProperties": true }, "extraction_results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["title", "slug", "status", "word_count", "credits_used"], "additionalProperties": true }, "AutopilotQueuedResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["processing"] }, "queued": { "type": "boolean", "enum": [true] }, "topic": { "type": "string" }, "message": { "type": "string" } }, "required": ["id", "status", "queued", "message"], "additionalProperties": false }, "ArticleSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "word_count": { "type": ["integer", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": ["string", "null"], "format": "date-time" } }, "required": ["id", "title", "slug", "status", "created_at"], "additionalProperties": false }, "ListArticlesResponse": { "type": "object", "properties": { "articles": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleSummary" } }, "total_articles": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "credits_used": { "type": "number" } }, "required": [ "articles", "total_articles", "limit", "offset", "credits_used" ], "additionalProperties": false }, "AdaptRequest": { "type": "object", "properties": { "article_id": { "type": "string", "format": "uuid" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "x_article", "x_thread", "linkedin", "facebook", "reddit", "threads", "instagram" ] }, "minItems": 1, "maxItems": 3, "uniqueItems": true }, "include_ref_link": { "type": "boolean", "default": true } }, "required": ["article_id", "platforms"], "additionalProperties": false }, "AdaptationItem": { "type": "object", "properties": { "adaptationId": { "type": "string", "format": "uuid", "description": "Adaptation UUID — pass directly to publish endpoint" }, "accountId": { "type": ["string", "null"], "format": "uuid", "description": "Social account UUID — pass directly to publish endpoint (null if not connected)" }, "platform": { "type": "string" }, "content": { "type": "string" }, "credits_used": { "type": "number" }, "char_count": { "type": "integer" }, "published": { "type": "boolean" }, "platform_post_id": { "type": ["string", "null"] } }, "required": [ "adaptationId", "accountId", "platform", "content", "credits_used", "char_count", "published", "platform_post_id" ], "additionalProperties": false }, "AdaptResponse": { "type": "object", "properties": { "adaptations": { "type": "array", "items": { "$ref": "#/components/schemas/AdaptationItem" } }, "total_credits": { "type": "number" }, "ref_link_appended": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "error": { "type": "string" } }, "required": ["platform", "error"], "additionalProperties": false } } }, "required": ["adaptations", "total_credits", "ref_link_appended"], "additionalProperties": false }, "CreateSessionRequest": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 5 }, "problems": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 20 }, "languages": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 5 }, "default": ["en"] }, "interval_minutes": { "type": "integer", "minimum": 60, "maximum": 10080, "default": 720 }, "article_size": { "type": "string", "enum": ["mini", "standard", "full", "pillar"], "default": "mini" }, "disable_competition": { "type": "boolean", "default": false } }, "required": ["categories"], "additionalProperties": false }, "CreateSessionResponse": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "interval_minutes": { "type": "integer" }, "article_size": { "type": "string" }, "estimated_credits_per_article": { "type": "number" }, "topic_catalog_size": { "type": "integer" }, "next_run_at": { "type": ["string", "null"], "format": "date-time" }, "created_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "session_id", "status", "categories", "languages", "interval_minutes", "article_size", "estimated_credits_per_article", "topic_catalog_size" ], "additionalProperties": false }, "CreateLeadMagnetRequest": { "type": "object", "properties": { "topic": { "type": "string", "minLength": 3, "maxLength": 200 }, "type": { "type": "string", "enum": ["checklist", "swipe_file", "framework"] }, "niche": { "type": "string", "maxLength": 100 }, "language": { "type": "string", "enum": ["en", "pt", "de", "es", "fr", "it"], "default": "en" }, "platform": { "type": "string", "enum": ["twitter", "linkedin"], "default": "twitter" }, "generate_images": { "type": "boolean", "default": false }, "auto_publish": { "type": "boolean", "default": false } }, "required": ["topic", "type"], "additionalProperties": false }, "CreateLeadMagnetResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["generating"] }, "type": { "type": "string" }, "topic": { "type": "string" }, "credits_charged": { "type": "number" }, "auto_publish": { "type": "boolean" } }, "required": [ "id", "status", "type", "topic", "credits_charged", "auto_publish" ], "additionalProperties": false }, "LeadMagnetGeneratingResponse": { "type": "object", "description": "Returned while the lead magnet is still being generated.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["generating"] }, "type": { "type": "string" }, "topic": { "type": "string" }, "progress": { "type": ["object", "null"], "properties": { "stage": { "type": "string" }, "percent": { "type": "number" }, "message": { "type": "string" } }, "required": ["stage", "percent", "message"], "additionalProperties": false } }, "required": ["id", "status", "type", "topic"], "additionalProperties": false }, "LeadMagnetCompletedResponse": { "type": "object", "description": "Returned when the lead magnet is completed, published, or archived.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["completed", "published", "archived"] }, "title": { "type": "string" }, "type": { "type": "string" }, "topic": { "type": "string" }, "public_slug": { "type": ["string", "null"] }, "public_url": { "type": ["string", "null"], "format": "uri" }, "pdf_url": { "type": ["string", "null"], "format": "uri" }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "status", "title", "type", "topic", "created_at"], "additionalProperties": false }, "CreateWarmLeadRunRequest": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "One company domain. Bare domains and http(s) URLs are accepted, but paths/social profile URLs are rejected." }, "icp": { "type": "string", "enum": ["seo-geo-agency", "content-led-saas", "vertical-saas"], "description": "Ideal customer profile. Defaults to content-led-saas when omitted." }, "buyerRoles": { "type": "array", "maxItems": 6, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "maxContacts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Maximum buyer candidates. Defaults to 3 when omitted." }, "drafts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Maximum outreach drafts. Defaults to 3 when omitted." }, "freshnessDays": { "type": "integer", "minimum": 7, "maximum": 365, "description": "Evidence lookback window in days. Defaults to 90 when omitted." }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": ["domain"], "additionalProperties": false }, "CreateWarmLeadRunResponse": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/WarmLeadRun" }, "credits_charged": { "type": "integer", "minimum": 0 }, "idempotent": { "type": "boolean" } }, "required": ["run", "credits_charged"], "additionalProperties": false }, "WarmLeadRunResponse": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/WarmLeadRun" } }, "required": ["run"], "additionalProperties": false }, "WarmLeadRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "signals_running", "contacts_running", "drafting_running", "completed", "blocked", "failed" ] }, "domain": { "type": "string" }, "normalized_domain": { "type": "string" }, "credits_charged": { "type": "integer", "minimum": 0 }, "blocked_reason": { "type": ["string", "null"] }, "error_message": { "type": ["string", "null"] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/WarmLeadResult" }, { "type": "null" } ] }, "provider_counters": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "id", "status", "domain", "normalized_domain", "credits_charged", "created_at", "updated_at" ], "additionalProperties": false }, "WarmLeadResult": { "type": "object", "description": "Canonical JSON warm-lead result. CSV and XLSX exports are flattened projections of this object.", "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["completed", "blocked", "failed"] }, "account": { "type": "object", "additionalProperties": true }, "signals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "contacts": { "type": "array", "maxItems": 3, "items": { "type": "object", "additionalProperties": true } }, "scoring": { "type": "object", "additionalProperties": true }, "drafts": { "type": "array", "maxItems": 3, "items": { "type": "object", "additionalProperties": true } }, "policy": { "type": "object", "additionalProperties": true }, "counters": { "type": "object", "additionalProperties": true }, "exportRows": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "exportUrls": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "runId", "status", "account", "signals", "contacts", "scoring", "drafts", "policy", "counters" ], "additionalProperties": true }, "UpdateLeadMagnetRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": ["published", "archived"] } }, "required": ["status"], "additionalProperties": false }, "IngestJobStatus": { "type": "string", "enum": ["processing", "completed", "failed"] }, "IngestContentType": { "type": "string", "enum": [ "youtube_video", "web_article", "pdf_document", "audio_file", "podcast_episode" ] }, "IngestJobSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/IngestJobStatus" }, "content_type": { "$ref": "#/components/schemas/IngestContentType" }, "created_at": { "type": "string", "format": "date-time" } }, "required": ["id", "tenant_id", "status", "content_type", "created_at"], "additionalProperties": false }, "IngestListResponse": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/IngestJobSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": ["jobs", "total", "limit", "offset"], "additionalProperties": false }, "IngestCreateRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": ["url"], "additionalProperties": false }, "IngestCreatedResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["processing"] }, "content_type": { "$ref": "#/components/schemas/IngestContentType" }, "credits_charged": { "type": "integer" }, "poll_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "content_type", "credits_charged", "poll_url" ], "additionalProperties": false }, "IngestMetadata": { "type": "object", "properties": { "title": { "type": ["string", "null"] }, "author": { "type": ["string", "null"] }, "duration_seconds": { "type": ["integer", "null"] }, "published_at": { "type": ["string", "null"] }, "language": { "type": ["string", "null"] }, "tags": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "IngestCachedResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["completed"] }, "cached": { "type": "boolean", "enum": [true] }, "content_type": { "$ref": "#/components/schemas/IngestContentType" }, "source_url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/IngestMetadata" }, "word_count": { "type": "integer" }, "credits_charged": { "type": "integer" }, "file_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "cached", "content_type", "source_url", "summary", "metadata", "word_count", "credits_charged", "file_url" ], "additionalProperties": false }, "IngestJobStatusResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/IngestJobStatus" }, "content_type": { "$ref": "#/components/schemas/IngestContentType" }, "source_url": { "type": "string", "format": "uri" }, "summary": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/IngestMetadata" }, "word_count": { "type": "integer" }, "credits_charged": { "type": "integer" }, "file_url": { "type": "string", "format": "uri" }, "error": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" } }, "required": ["id", "status"], "additionalProperties": false }, "IngestBatchRequest": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 20 }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": ["urls"], "additionalProperties": false }, "IngestBatchResultItem": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": ["accepted", "cached", "error"] }, "job_id": { "type": "string", "format": "uuid" }, "error": { "type": "string" }, "credits_charged": { "type": "integer" } }, "required": ["url", "status", "credits_charged"], "additionalProperties": false }, "IngestBatchResponse": { "type": "object", "properties": { "total": { "type": "integer" }, "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IngestBatchResultItem" } } }, "required": ["total", "accepted", "failed", "results"], "additionalProperties": false }, "CompetitorDiscoverRequest": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 5 } }, "required": ["keywords"], "additionalProperties": false }, "CompetitorItem": { "type": "object", "properties": { "domain": { "type": "string" }, "source_mode": { "type": "string", "enum": [ "dataforseo_metrics", "live_google_serp", "similarity" ] }, "visibility": { "type": "number", "minimum": 0 }, "keywords_count": { "type": "integer" }, "avg_position": { "type": "number" }, "etv": { "type": "number" }, "evidence": { "type": "object", "properties": { "queries_matched": { "type": "integer" }, "best_position": { "type": "number" }, "example_urls": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": [ "queries_matched", "best_position", "example_urls" ], "additionalProperties": false } }, "required": [ "domain" ], "additionalProperties": false }, "CompetitorDiscoverResponse": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" } }, "competitors_found": { "type": "integer" }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorItem" } }, "credits_used": { "type": "integer" } }, "required": [ "keywords", "competitors_found", "competitors", "credits_used" ], "additionalProperties": false }, "CompetitorScoutRequest": { "type": "object", "properties": { "domain": { "type": "string", "format": "uri" }, "mode": { "type": "string", "enum": ["fast", "ultimate"], "default": "fast" }, "topic": { "type": "string", "minLength": 1, "maxLength": 500 }, "language": { "type": "string", "minLength": 2, "maxLength": 5, "default": "en" } }, "required": ["domain"], "additionalProperties": false }, "CompetitorIntelligence": { "type": "object", "properties": { "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "opportunities": { "type": "array", "items": { "type": "string" } }, "threats": { "type": "array", "items": { "type": "string" } }, "content_strategy": { "type": "string" }, "estimated_monthly_traffic": { "type": "integer" }, "top_content_categories": { "type": "array", "items": { "type": "string" } } }, "required": [ "strengths", "weaknesses", "opportunities", "threats", "content_strategy", "estimated_monthly_traffic", "top_content_categories" ], "additionalProperties": false }, "CompetitorScoutResponse": { "type": "object", "properties": { "domain": { "type": "string" }, "mode": { "type": "string", "enum": ["fast", "ultimate"] }, "intelligence": { "$ref": "#/components/schemas/CompetitorIntelligence" }, "credits_used": { "type": "integer" } }, "required": ["domain", "mode", "intelligence", "credits_used"], "additionalProperties": false }, "WebhookEventType": { "type": "string", "enum": [ "article.generated", "article.failed", "lead_magnet.ready", "lead_magnet.failed", "ingestion.completed", "ingestion.failed", "social_adaptation.generated", "scout.results_ready", "scout.dispatched", "session.articles_generated", "billing.credits_low", "billing.credits_empty", "agent_worker.published", "agent_worker.competitor_diff_detected", "agent_worker.budget_exhausted", "agent_worker.paused", "agent_worker.run_failed", "agent_worker.approval_requested" ] }, "WebhookDeliveryStatus": { "type": "string", "enum": ["queued", "delivering", "delivered", "failed", "dead_lettered"] }, "WebhookRegisterRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048 }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "maxItems": 32 }, "description": { "type": "string", "maxLength": 300 } }, "required": ["url"], "additionalProperties": false }, "WebhookRegisterResponse": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "secret": { "type": "string" }, "event_types": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "webhook_id", "url", "secret", "event_types", "created_at" ], "additionalProperties": false }, "WebhookEndpointSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "event_types": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "is_active": { "type": "boolean" }, "description": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "event_types", "is_active", "description", "created_at", "updated_at" ], "additionalProperties": false }, "WebhookListResponse": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointSummary" } } }, "required": ["webhooks"], "additionalProperties": false }, "WebhookDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] }, "webhook_id": { "type": "string", "format": "uuid" } }, "required": ["success", "webhook_id"], "additionalProperties": false }, "WebhookDeliveryItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempts": { "type": "integer" }, "last_http_status": { "type": ["integer", "null"] }, "last_error": { "type": ["string", "null"] }, "duration_ms": { "type": ["integer", "null"] }, "delivered_at": { "type": ["string", "null"], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": ["object", "null"], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] } }, "required": ["id", "url", "description"], "additionalProperties": false } }, "required": [ "id", "event_id", "event_type", "status", "attempts", "last_http_status", "last_error", "duration_ms", "delivered_at", "created_at", "updated_at", "endpoint" ], "additionalProperties": false }, "WebhookDeliveryListResponse": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryItem" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": ["deliveries", "total", "limit", "offset"], "additionalProperties": false }, "PersonaItem": { "type": "object", "properties": { "slug": { "type": "string" }, "displayName": { "type": "string" }, "group": { "type": "string" }, "description": { "type": "string" } }, "required": ["slug", "displayName", "group", "description"], "additionalProperties": false }, "PersonasResponse": { "type": "object", "properties": { "personas": { "type": "array", "items": { "$ref": "#/components/schemas/PersonaItem" } }, "total": { "type": "integer" }, "usage": { "type": "string" } }, "required": ["personas", "total", "usage"], "additionalProperties": false }, "PublishRequest": { "oneOf": [ { "$ref": "#/components/schemas/PublishAdaptationRequest" }, { "$ref": "#/components/schemas/PublishRawRequest" } ], "discriminator": { "propertyName": "action", "mapping": { "now": "#/components/schemas/PublishAdaptationRequest", "schedule": "#/components/schemas/PublishAdaptationRequest", "cancel": "#/components/schemas/PublishAdaptationRequest", "publish_raw": "#/components/schemas/PublishRawRequest" } } }, "PublishAdaptationRequest": { "type": "object", "properties": { "adaptationId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": ["now", "schedule", "cancel"] }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Required if action=schedule. Must be a future date." }, "platform": { "type": "string", "enum": [ "facebook", "linkedin", "x_article", "x_thread", "reddit", "threads", "instagram", "instagram_reels", "youtube_shorts" ] }, "accountId": { "type": "string", "format": "uuid" } }, "required": ["adaptationId", "action", "platform", "accountId"], "additionalProperties": false }, "PublishRawRequest": { "type": "object", "description": "Direct publish article content as-is to a social platform. No AI adaptation, 0 credits.", "properties": { "action": { "type": "string", "enum": ["publish_raw"] }, "articleId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": ["linkedin", "facebook", "x_article", "reddit", "instagram"] }, "accountId": { "type": "string", "format": "uuid" }, "subreddit": { "type": "string", "description": "Required when platform is reddit" } }, "required": ["action", "articleId", "platform", "accountId"], "additionalProperties": false }, "PublishResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "action": { "type": "string", "enum": ["now", "schedule", "cancel", "publish_raw"] }, "adaptationId": { "type": "string", "format": "uuid" }, "postId": { "type": ["string", "null"], "description": "Present when action=now" }, "platformPostId": { "type": ["string", "null"], "description": "Present when action=publish_raw" }, "scheduledAt": { "type": ["string", "null"], "format": "date-time", "description": "Present when action=schedule" }, "messageId": { "type": ["string", "null"], "description": "QStash message ID for scheduled publish" }, "deduplicated": { "type": "boolean", "description": "True if publish was skipped because already published" }, "warning": { "type": "string", "description": "Present when publish_raw encounters a non-fatal issue" } }, "required": ["success", "action", "adaptationId"], "additionalProperties": false }, "ScheduleItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["article", "post", "social_adaptation"] }, "title": { "type": "string" }, "platform": { "type": ["string", "null"], "description": "Only for social_adaptation type" }, "scheduledAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" } }, "required": ["id", "type", "title", "scheduledAt", "status"], "additionalProperties": false }, "ScheduleListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleItem" } }, "total": { "type": "integer" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "required": ["items", "total", "from", "to"], "additionalProperties": false }, "ScheduleGapItem": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "scheduled": { "type": "integer" }, "target": { "type": "integer" } }, "required": ["date", "scheduled", "target"], "additionalProperties": false }, "ScheduleGapsResponse": { "type": "object", "properties": { "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleGapItem" } }, "totalGaps": { "type": "integer" }, "daysAnalyzed": { "type": "integer" }, "postsPerDay": { "type": "integer" } }, "required": ["gaps", "totalGaps", "daysAnalyzed", "postsPerDay"], "additionalProperties": false }, "ScheduleSuggestResponse": { "type": "object", "properties": { "slots": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "postsPerDay": { "type": "integer" }, "timezone": { "type": "string" }, "source": { "type": "string", "enum": ["custom", "recommended"] } }, "required": ["slots", "postsPerDay", "timezone", "source"], "additionalProperties": false }, "PublishSchedule": { "type": "object", "properties": { "postsPerDay": { "type": "integer", "minimum": 1, "maximum": 10, "default": 2 }, "slots": { "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "maxItems": 48 } }, "required": ["postsPerDay"], "additionalProperties": false }, "AgentSettingsResponse": { "type": "object", "properties": { "defaultPlatforms": { "type": "array", "items": { "type": "string", "enum": [ "linkedin", "x_article", "x_thread", "facebook", "reddit", "threads", "instagram" ] }, "maxItems": 10 }, "imageStylePreset": { "type": "string", "enum": ["minimal", "tech", "bold"], "default": "minimal" }, "contentTone": { "type": "string", "enum": ["professional", "casual", "bold"], "default": "professional" }, "publishSchedule": { "$ref": "#/components/schemas/PublishSchedule" }, "targetTimezone": { "type": "string", "default": "America/New_York" }, "trustLevel": { "type": "string", "enum": ["ask_all", "show_preview", "autopilot"], "default": "show_preview" }, "scanSources": { "type": "array", "items": { "type": "string", "enum": ["x", "google", "hn", "reddit", "producthunt"] } } }, "required": [ "defaultPlatforms", "imageStylePreset", "contentTone", "publishSchedule", "targetTimezone", "trustLevel", "scanSources" ], "additionalProperties": false }, "UpdateAgentSettingsRequest": { "type": "object", "description": "All fields optional — partial update", "properties": { "defaultPlatforms": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "imageStylePreset": { "type": "string", "enum": ["minimal", "tech", "bold"] }, "contentTone": { "type": "string", "enum": ["professional", "casual", "bold"] }, "publishSchedule": { "$ref": "#/components/schemas/PublishSchedule" }, "targetTimezone": { "type": "string" }, "trustLevel": { "type": "string", "enum": ["ask_all", "show_preview", "autopilot"] }, "scanSources": { "type": "array", "items": { "type": "string", "enum": ["x", "google", "hn", "reddit", "producthunt"] } } }, "additionalProperties": false }, "CreatePostRequest": { "type": "object", "properties": { "topic": { "type": "string", "minLength": 1, "maxLength": 500 }, "platforms": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 7 }, "tone": { "type": "string", "maxLength": 100 }, "imageStyle": { "type": "string", "maxLength": 100 }, "scheduledAt": { "type": "string", "format": "date-time", "description": "Must be future date if provided" }, "contentType": { "type": "string", "enum": ["short", "detailed"], "default": "short" } }, "required": ["topic"], "additionalProperties": false }, "CreatePostResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "postId": { "type": "string", "format": "uuid" }, "adaptations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform": { "type": "string" } }, "required": ["id", "platform"] } }, "scheduledAt": { "type": ["string", "null"], "format": "date-time" } }, "required": ["success", "postId", "adaptations", "scheduledAt"], "additionalProperties": false }, "ScanRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "mode": { "type": "string", "enum": ["fast", "deep", "ultra"] }, "limit": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } }, "required": ["query", "mode"], "additionalProperties": false }, "ScanResult": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 }, "summary": { "type": "string", "maxLength": 300 }, "url": { "type": "string", "format": "uri" }, "source": { "type": "string", "enum": ["x", "web", "hackernews"] }, "relevance": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": ["title", "summary", "url", "source", "relevance"], "additionalProperties": false }, "ScanResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "mode": { "type": "string", "enum": ["fast", "deep", "ultra"] }, "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScanResult" } }, "cost": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": ["success", "mode", "query", "results", "cost"], "additionalProperties": false }, "UpdateImageStyleRequest": { "type": "object", "properties": { "preset": { "type": "string", "enum": ["minimal", "tech", "bold"] } }, "required": ["preset"], "additionalProperties": false }, "UpdateImageStyleResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "preset": { "type": "string" } }, "required": ["success", "preset"], "additionalProperties": false }, "AgentStatusAction": { "type": "object", "required": ["severity", "title", "message"], "properties": { "severity": { "type": "string", "enum": ["critical", "warning", "info"] }, "title": { "type": "string" }, "message": { "type": "string" }, "command": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "AgentStatusPlatformConnection": { "type": "object", "required": ["platform", "account_name"], "properties": { "platform": { "type": "string" }, "account_name": { "type": ["string", "null"] } } }, "AgentStatusResponse": { "type": "object", "required": [ "summary", "billing", "social", "schedule", "knowledge", "content", "tenant", "actions", "generated_at" ], "properties": { "summary": { "type": "object", "required": [ "operational_status", "ready_to_create", "ready_to_publish", "blockers_count", "warnings_count" ], "properties": { "operational_status": { "type": "string", "enum": ["ready", "attention", "blocked"] }, "ready_to_create": { "type": "boolean" }, "ready_to_publish": { "type": "boolean" }, "blockers_count": { "type": "integer", "minimum": 0 }, "warnings_count": { "type": "integer", "minimum": 0 } } }, "billing": { "type": "object", "required": ["credits_available", "status", "topup_url"], "properties": { "credits_available": { "type": "number" }, "status": { "type": "string", "enum": ["healthy", "low", "empty"] }, "topup_url": { "type": "string", "format": "uri" } } }, "social": { "type": "object", "required": [ "connected_count", "connected_platforms", "default_platforms", "missing_default_platforms", "connect_url" ], "properties": { "connected_count": { "type": "integer", "minimum": 0 }, "connected_platforms": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStatusPlatformConnection" } }, "default_platforms": { "type": "array", "items": { "type": "string" } }, "missing_default_platforms": { "type": "array", "items": { "type": "string" } }, "connect_url": { "type": "string", "format": "uri" } } }, "schedule": { "type": "object", "required": [ "timezone", "posts_per_day_target", "next_publish_at", "scheduled_24h", "scheduled_7d", "gaps_count_7d", "calendar_url" ], "properties": { "timezone": { "type": "string" }, "posts_per_day_target": { "type": "integer", "minimum": 1 }, "next_publish_at": { "type": ["string", "null"], "format": "date-time" }, "scheduled_24h": { "type": "integer", "minimum": 0 }, "scheduled_7d": { "type": "integer", "minimum": 0 }, "gaps_count_7d": { "type": "integer", "minimum": 0 }, "calendar_url": { "type": "string", "format": "uri" } } }, "knowledge": { "type": "object", "required": [ "has_documents", "documents_count", "last_document_at", "add_documents_command", "add_documents_url" ], "properties": { "has_documents": { "type": "boolean" }, "documents_count": { "type": "integer", "minimum": 0 }, "last_document_at": { "type": ["string", "null"], "format": "date-time" }, "add_documents_command": { "type": "string" }, "add_documents_url": { "type": "string", "format": "uri" } } }, "content": { "type": "object", "required": [ "has_content", "total_items", "latest_article_at", "latest_post_at", "create_post_command", "create_article_command" ], "properties": { "has_content": { "type": "boolean" }, "total_items": { "type": "integer", "minimum": 0 }, "latest_article_at": { "type": ["string", "null"], "format": "date-time" }, "latest_post_at": { "type": ["string", "null"], "format": "date-time" }, "create_post_command": { "type": "string" }, "create_article_command": { "type": "string" } } }, "tenant": { "type": "object", "required": ["blog_url", "blog_handle"], "properties": { "blog_url": { "type": ["string", "null"], "format": "uri" }, "blog_handle": { "type": ["string", "null"] } } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStatusAction" } }, "generated_at": { "type": "string", "format": "date-time" } } }, "ProductCreateRequest": { "type": "object", "required": ["title", "content"], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "content": { "type": "string", "minLength": 1, "maxLength": 500000 }, "source_type": { "type": "string", "enum": ["upload", "url", "manual"], "default": "upload" }, "source_name": { "type": "string", "maxLength": 500 }, "source_url": { "type": "string", "format": "uri", "maxLength": 2000 } }, "additionalProperties": false }, "ProductCreateResponse": { "type": "object", "required": [ "id", "title", "source_type", "chunks_count", "chunks_failed", "partial", "token_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source_type": { "type": "string" }, "chunks_count": { "type": "integer", "minimum": 0 }, "chunks_failed": { "type": "integer", "minimum": 0 }, "partial": { "type": "boolean" }, "token_count": { "type": "integer", "minimum": 0 } } }, "ProductDocumentSummary": { "type": "object", "required": [ "id", "title", "source_type", "source_name", "token_count", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source_type": { "type": "string" }, "source_name": { "type": ["string", "null"] }, "token_count": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" } } }, "ProductListResponse": { "type": "object", "required": ["documents"], "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/ProductDocumentSummary" } } } }, "ProductDeleteResponse": { "type": "object", "required": ["success"], "properties": { "success": { "type": "boolean" } } }, "ProductSearchRequest": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 } }, "additionalProperties": false }, "ProductSearchResultItem": { "type": "object", "required": ["document_id", "content", "similarity"], "properties": { "document_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "similarity": { "type": "number" } } }, "ProductSearchResponse": { "type": "object", "required": ["results"], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSearchResultItem" } } } }, "ShortsGenerateRequest": { "type": "object", "required": ["prompt", "avatar_url", "duration"], "properties": { "article_id": { "type": "string", "format": "uuid", "description": "Optional article ID. When provided, shorts_video_url is saved to article metadata on completion." }, "prompt": { "type": "string", "minLength": 10, "maxLength": 2000 }, "avatar_url": { "type": "string", "format": "uri" }, "duration": { "type": "integer", "enum": [5, 10, 15] }, "resolution": { "type": "string", "enum": ["480p", "720p"], "default": "480p" }, "aspect_ratio": { "type": "string", "enum": ["9:16", "16:9", "1:1"], "default": "9:16" }, "speech_text": { "type": "string", "minLength": 5, "maxLength": 1000 } }, "additionalProperties": false }, "ShortsGenerateAcceptedResponse": { "type": "object", "required": [ "id", "status", "video_url", "credits_charged", "estimated_seconds" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["generating"] }, "video_url": { "type": ["string", "null"] }, "credits_charged": { "type": "integer", "minimum": 0 }, "estimated_seconds": { "type": "integer", "minimum": 1 } } }, "ShortsProviderAttempt": { "type": "object", "required": [ "provider", "model", "status", "requestedDurationSeconds", "providerBilledSeconds", "generationCostUsd", "costSource" ], "properties": { "provider": { "type": "string", "enum": ["xAI", "Veo", "Veo+Merge"] }, "model": { "type": "string" }, "status": { "type": "string", "enum": ["started", "succeeded", "failed", "skipped"] }, "requestedDurationSeconds": { "type": "integer", "enum": [5, 10, 15] }, "providerBilledSeconds": { "type": "number", "minimum": 0 }, "generationCostUsd": { "type": "number", "minimum": 0 }, "costSource": { "type": "string" }, "error": { "type": "string" } } }, "ShortsStatusResponse": { "type": "object", "required": [ "id", "status", "credits_charged", "video_url", "error", "subtitles_applied", "subtitle_warning", "provider_attempts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["generating", "completed", "failed"] }, "credits_charged": { "type": "integer", "minimum": 0 }, "video_url": { "type": ["string", "null"], "format": "uri" }, "error": { "type": ["string", "null"] }, "subtitles_applied": { "type": "boolean" }, "subtitle_warning": { "type": ["string", "null"] }, "provider": { "type": ["string", "null"], "description": "Provider that produced the completed video." }, "model": { "type": ["string", "null"], "description": "Provider model used for the completed video." }, "provider_strategy": { "type": ["string", "null"], "description": "Requested provider strategy for the completed video." }, "requested_duration_seconds": { "type": ["integer", "null"], "enum": [5, 10, 15, null] }, "actual_duration_seconds": { "type": ["number", "null"] }, "provider_billed_seconds": { "type": ["integer", "null"] }, "billed_duration": { "type": ["integer", "null"], "enum": [5, 10, 15, null] }, "generation_cost_usd": { "type": ["number", "null"] }, "generation_cost_source": { "type": ["string", "null"] }, "provider_attempts": { "type": "array", "items": { "$ref": "#/components/schemas/ShortsProviderAttempt" } }, "downgraded_from_duration": { "type": ["integer", "null"], "enum": [5, 10, 15, null] } } }, "ShortsScriptRequest": { "type": "object", "required": ["topic"], "properties": { "topic": { "type": "string", "minLength": 3, "maxLength": 500 }, "product_id": { "type": "string", "format": "uuid" }, "article_id": { "type": "string", "format": "uuid", "description": "Optional article ID. When provided, shorts_title, shorts_hashtags, and shorts_script are saved to article metadata." }, "duration": { "type": "string", "enum": ["short", "long"], "default": "short" }, "requested_duration_seconds": { "type": "integer", "enum": [5, 10, 15], "description": "Exact target runtime in seconds. When present, this controls the script word budget." }, "style": { "type": "string", "enum": ["hook", "educational", "cta"], "default": "hook" }, "language": { "type": "string", "minLength": 2, "maxLength": 5, "default": "en" } }, "additionalProperties": false }, "ShortsScriptResponse": { "type": "object", "required": [ "script", "title", "hashtags", "word_count", "estimated_duration_sec", "parts", "credits_charged" ], "properties": { "script": { "type": "string", "description": "Voiceover script text (also used as post description)" }, "title": { "type": "string", "description": "Catchy video title (max 100 chars), used as YouTube/TikTok title" }, "hashtags": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "2-3 relevant hashtags with # prefix" }, "word_count": { "type": "integer", "minimum": 1 }, "estimated_duration_sec": { "type": "integer", "minimum": 1 }, "parts": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "credits_charged": { "type": "integer", "minimum": 0 } } }, "ShortsAvatarRequest": { "type": "object", "required": ["gender", "origin"], "properties": { "gender": { "type": "string", "enum": ["male", "female"] }, "origin": { "type": "string", "enum": [ "european", "asian", "african", "latin", "middle_eastern", "south_asian" ] }, "age_range": { "type": "string", "enum": ["18-25", "26-35", "36-50"], "default": "26-35" }, "type": { "type": "string", "enum": ["tech_founder", "vibe_coder", "student", "executive"], "default": "tech_founder" }, "location": { "type": "string", "enum": [ "coffee_shop", "dev_cave", "street", "car", "home_office", "podcast_studio", "glass_office", "rooftop", "bedroom", "park", "gym" ], "default": "coffee_shop" } }, "additionalProperties": false }, "ShortsAvatarResponse": { "type": "object", "required": [ "avatar_url", "r2_key", "credits_charged", "prompt_used", "prompt_meta" ], "properties": { "avatar_url": { "type": "string", "format": "uri" }, "r2_key": { "type": "string" }, "credits_charged": { "type": "integer", "minimum": 0 }, "prompt_used": { "type": "string", "description": "Full image prompt used for this generation (same input params can yield different prompts for diversity)." }, "prompt_meta": { "$ref": "#/components/schemas/ShortsAvatarPromptMeta" } } }, "ShortsAvatarPromptMeta": { "type": "object", "required": ["age_years", "variation_tags"], "properties": { "age_years": { "type": "integer", "minimum": 18, "maximum": 50 }, "variation_tags": { "type": "array", "items": { "type": "string" }, "description": "Server-sampled appearance and location tags for debugging and diversity checks." } } }, "ShortsMergePhraseItem": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "ShortsMergeConfig": { "type": "object", "properties": { "words_per_phrase": { "type": "integer", "minimum": 2, "maximum": 8 }, "font_size": { "type": "integer", "minimum": 16, "maximum": 72 }, "position_from_bottom": { "type": "integer", "minimum": 50, "maximum": 300 }, "text_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$|^[a-z]{3,20}$", "description": "Hex color (#FFFFFF) or named color" }, "stroke_color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$|^[a-z]{3,20}$", "description": "Hex color (#FFFFFF) or named color" }, "stroke_width": { "type": "integer", "minimum": 0, "maximum": 5 } }, "additionalProperties": false }, "ShortsPublishTarget": { "type": "object", "required": ["platform", "account_id"], "properties": { "platform": { "type": "string", "enum": ["youtube_shorts", "instagram_reels", "tiktok"] }, "account_id": { "type": "string", "format": "uuid", "description": "Connected social account ID" } }, "additionalProperties": false }, "ShortsPublishRequest": { "type": "object", "required": ["video_url", "speech_text", "targets"], "properties": { "video_url": { "type": "string", "format": "uri", "description": "HTTPS URL of the video. Must be hosted on download.citedy.com (path must start with `/agent/shorts/` or `/agent/reels/`) or Supabase storage. The R2 prefix restriction ensures Meta's `facebookexternalhit` crawler can fetch the video via our `/media/shorts/...` proxy on www.citedy.com — direct R2 URLs are blocked by the bucket's default `Disallow: /` robots.txt and cause Instagram Reel publish to fail." }, "speech_text": { "type": "string", "minLength": 5, "maxLength": 2000, "description": "Spoken text from the video for metadata generation" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/ShortsPublishTarget" }, "minItems": 1, "maxItems": 3, "description": "Platforms to publish to (max 3). Duplicate platforms are rejected by runtime validation." }, "privacy_status": { "type": "string", "enum": ["public", "unlisted", "private"], "description": "Publish privacy. YouTube supports public/unlisted/private. TikTok uses tiktok_privacy_level from the account's current creator_info options; privacy_status=private remains a compatibility fallback for SELF_ONLY. Instagram Reels ignores this field." }, "tiktok_privacy_level": { "type": "string", "enum": [ "PUBLIC_TO_EVERYONE", "FOLLOWER_OF_CREATOR", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY" ], "description": "TikTok-only visibility level selected from the account's current TikTok creator_info options." }, "tiktok_title": { "type": "string", "minLength": 1, "maxLength": 2200, "description": "TikTok-only reviewed post title/caption." }, "tiktok_disable_comment": { "type": "boolean", "description": "TikTok-only flag to disable comments for the post." }, "tiktok_disable_duet": { "type": "boolean", "description": "TikTok-only flag to disable duets for the post." }, "tiktok_disable_stitch": { "type": "boolean", "description": "TikTok-only flag to disable stitches for the post." }, "tiktok_brand_content_toggle": { "type": "boolean", "description": "TikTok-only commercial disclosure flag for third-party branded content. Branded content cannot use SELF_ONLY visibility." }, "tiktok_brand_organic_toggle": { "type": "boolean", "description": "TikTok-only commercial disclosure flag for content promoting the creator's own brand." }, "tiktok_is_aigc": { "type": "boolean", "description": "TikTok-only flag indicating AI-generated content." } }, "allOf": [ { "if": { "properties": { "targets": { "contains": { "type": "object", "properties": { "platform": { "const": "tiktok" } }, "required": ["platform"] } } }, "required": ["targets"] }, "then": { "anyOf": [ { "required": ["tiktok_title", "tiktok_privacy_level"] }, { "properties": { "privacy_status": { "const": "private" } }, "required": ["tiktok_title", "privacy_status"] } ] } } ], "additionalProperties": false }, "ShortsPublishResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "ok": { "type": "boolean" }, "post_id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false } } } }, "metadata_provider": { "type": "string", "description": "LLM provider used for metadata generation" }, "metadata_degraded": { "type": "boolean", "description": "True if AI metadata generation failed and static fallback was used" }, "timings": { "type": "object", "properties": { "metadata_ms": { "type": "number" }, "total_ms": { "type": "number" } }, "additionalProperties": { "type": "number" } }, "credits_charged": { "type": "number" } } }, "ShortsMergeRequest": { "type": "object", "required": ["video_urls", "phrases"], "properties": { "video_urls": { "type": "array", "minItems": 2, "maxItems": 4, "items": { "type": "string", "format": "uri", "pattern": "^https://download\\.citedy\\.com/" }, "description": "2-4 video URLs hosted on download.citedy.com" }, "phrases": { "type": "array", "minItems": 2, "maxItems": 4, "items": { "$ref": "#/components/schemas/ShortsMergePhraseItem" }, "description": "Must contain exactly one phrase per video URL" }, "config": { "$ref": "#/components/schemas/ShortsMergeConfig" } }, "additionalProperties": false }, "ShortsMergeResponse": { "type": "object", "required": [ "video_url", "r2_key", "duration", "segment_durations", "credits_charged" ], "properties": { "video_url": { "type": "string", "format": "uri" }, "r2_key": { "type": "string" }, "duration": { "type": "number", "minimum": 0 }, "segment_durations": { "type": "array", "items": { "type": "number", "minimum": 0 } }, "credits_charged": { "type": "integer", "minimum": 0 } } }, "SeoToolUrlRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Target page URL." } } }, "SeoInternalLinksRequest": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Source page URL to analyze." }, "targetUrls": { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "uri" }, "default": [], "description": "Known target URLs for internal link opportunity analysis." }, "sitemapUrl": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Optional sitemap URL used when targetUrls are not provided." } } }, "SeoToolSuccessResponse": { "type": "object", "required": ["success", "tool", "data", "credits_charged"], "properties": { "success": { "type": "boolean", "example": true }, "tool": { "type": "string", "example": "meta-tags" }, "data": { "type": "object", "additionalProperties": true, "description": "Tool-specific diagnostics payload." }, "credits_charged": { "type": "integer", "minimum": 0, "example": 1 } } }, "SeoOgImageRequest": { "type": "object", "properties": { "brandName": { "type": "string", "maxLength": 100 }, "brandDescription": { "type": "string", "maxLength": 1000 }, "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "logoUrl": { "type": "string", "format": "uri", "maxLength": 2000 }, "template": { "type": "string", "enum": ["product", "blog_post", "comparison", "case_study"] }, "headline": { "type": "string", "maxLength": 120 }, "subheadline": { "type": "string", "maxLength": 180 } } }, "BrandScanStartRequest": { "type": "object", "required": ["brandName"], "properties": { "brandName": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "BrandScanProviderResult": { "type": "object", "required": ["llmId", "mentioned", "sentiment", "confidence"], "properties": { "llmId": { "type": "string", "enum": [ "chatgpt", "gemini", "perplexity", "claude", "deepseek", "grok" ] }, "mentioned": { "type": "boolean" }, "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative", "unknown"] }, "snippet": { "type": "string" }, "confidence": { "type": "number" }, "error": { "type": "string" } } }, "BrandScanStartResponse": { "type": "object", "required": ["id", "status", "brand_name", "credits_charged"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["processing"] }, "brand_name": { "type": "string" }, "credits_charged": { "type": "integer", "minimum": 0 } } }, "BrandScanStatusResponse": { "type": "object", "required": ["id", "status", "brand_name", "credits_charged"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["processing", "completed", "failed"] }, "brand_name": { "type": "string" }, "credits_charged": { "type": "integer", "minimum": 0 }, "overall_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BrandScanProviderResult" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } }, "ArticleJobStatusResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "processing", "generated", "publishing", "published", "failed" ], "description": "processing — generation in progress. generated — draft, not yet published. publishing — publish pipeline triggered. published — live on blog. failed — generation or publish failed." }, "queued": { "type": "boolean" }, "topic": { "type": "string" }, "message": { "type": "string" }, "article_id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "article_url": { "type": "string", "format": "uri", "description": "URL where the article will be accessible once published. Returns 404 for draft (generated) articles until published." }, "mode": { "type": "string", "enum": ["standard", "turbo", "turbo+"] }, "word_count": { "type": "integer" }, "credits_used": { "type": "number" }, "estimated_total_credits": { "type": "number" }, "reason": { "type": "string" }, "error": { "type": "string" }, "trust_level": { "type": "string" }, "extensions": { "type": "object", "properties": { "illustrations": {}, "audio": {}, "competition_intelligence": { "type": "boolean" } } } }, "required": ["status"] } } } }