{ "openapi": "3.1.0", "info": { "title": "Trakkr API", "description": "Track your brand's visibility across AI search engines. Monitor how ChatGPT, Claude, Perplexity, and other AI models mention and recommend your brand. All endpoints authenticate with an API key (`Authorization: Bearer sk_live_...`). Unless an operation explicitly says it is idempotent, do not blindly retry a write after a timeout because the first attempt may have completed. There is no API-wide Idempotency-Key contract.", "version": "1.1.0", "contact": { "name": "Trakkr Support", "url": "https://trakkr.ai/support", "email": "support@trakkr.ai" }, "license": { "name": "Proprietary", "url": "https://trakkr.ai/terms" } }, "paths": { "/get-brands": { "get": { "tags": [ "public-api" ], "summary": "Get Brands", "description": "List all brands accessible to your API key.\n\nReturns brands available through direct membership, current team grants,\nor an active client assignment. Client assignments are always read-only.\nOptionally include markets, aliases, and/or the brand's own description with\n?include=markets,aliases,profile. Filter to a single brand with ?brand_id=X.", "operationId": "get_brands_get_brands_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single brand by UUID", "title": "Brand Id" }, "description": "Filter to a single brand by UUID" }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated: markets, aliases, profile", "title": "Include" }, "description": "Comma-separated: markets, aliases, profile" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandsExtendedResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-scores": { "get": { "tags": [ "public-api" ], "summary": "Get Scores", "description": "Get visibility scores and historical trends for a brand.\n\nViews:\n- summary (default): Current visibility, presence, rank, and historical trends\n- time_series: Daily visibility, presence, rank, mentions over time\n- by_model: Visibility breakdown by AI model\n- by_prompt: Visibility breakdown by tracked prompt", "operationId": "get_scores_get_scores_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "brand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias for brand_id", "title": "Brand" }, "description": "Alias for brand_id" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Historical period in days", "default": 90, "title": "Days" }, "description": "Historical period in days" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "View mode: summary (default), time_series, by_model, by_prompt", "title": "View" }, "description": "View mode: summary (default), time_series, by_model, by_prompt" }, { "name": "tag_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tag UUIDs to filter prompts", "title": "Tag Ids" }, "description": "Comma-separated tag UUIDs to filter prompts" }, { "name": "prompt_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Single prompt UUID to filter scores", "title": "Prompt Id" }, "description": "Single prompt UUID to filter scores" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScoresResponse" }, { "$ref": "#/components/schemas/VisibilityTimeSeriesResponse" }, { "$ref": "#/components/schemas/VisibilityByModelResponse" }, { "$ref": "#/components/schemas/VisibilityByPromptResponse" } ], "title": "Response Get Scores Get Scores Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-citations": { "get": { "tags": [ "public-api" ], "summary": "Get Citations", "description": "Get citation data for your brand. Use the `view` parameter to select different data views.\n\nViews:\n- list (default): Paginated citation URLs\n- history: Time series of citation counts, brand mentions, sentiment by date\n- queries: Query-level citation analytics with clustering\n- sources: Full domain profile (requires `domain` param)\n- feed: Paginated change feed (new/lost/changed citations)\n- heatmap: Brand vs competitors across sources matrix", "operationId": "get_citations_get_citations_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "View mode: list (default), history, queries, sources, feed, heatmap", "title": "View" }, "description": "View mode: list (default), history, queries, sources, feed, heatmap" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Results per page", "default": 100, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" }, { "name": "domain", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by domain (partial match). Required when view=sources.", "title": "Domain" }, "description": "Filter by domain (partial match). Required when view=sources." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Historical period in days (filters by last_seen date)", "default": 30, "title": "Days" }, "description": "Historical period in days (filters by last_seen date)" }, { "name": "days_back", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 30, "minimum": 1, "description": "Days back for feed comparison (for view=feed)", "default": 7, "title": "Days Back" }, "description": "Days back for feed comparison (for view=feed)" }, { "name": "tag_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tag UUIDs to filter by prompt tags", "title": "Tag Ids" }, "description": "Comma-separated tag UUIDs to filter by prompt tags" }, { "name": "prompt_text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter citations by prompt text (partial match)", "title": "Prompt Text" }, "description": "Filter citations by prompt text (partial match)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CitationsResponse" }, { "$ref": "#/components/schemas/CitationsHistoryResponse" }, { "$ref": "#/components/schemas/CitationsQueriesResponse" }, { "$ref": "#/components/schemas/CitationsSourceResponse" }, { "$ref": "#/components/schemas/CitationsFeedResponse" }, { "$ref": "#/components/schemas/CitationsHeatmapResponse" }, { "$ref": "#/components/schemas/CitationsAnalyticsResponse" }, { "$ref": "#/components/schemas/CitationDetailResponse" }, { "$ref": "#/components/schemas/CitationsByModelResponse" }, { "$ref": "#/components/schemas/CitationsTopPagesResponse" } ], "title": "Response Get Citations Get Citations Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-competitor-data": { "get": { "tags": [ "public-api" ], "summary": "Get Competitor Data", "description": "Get competitor analysis data. Use the `view` parameter to select different data views.\n\nViews:\n- summary (default): Performance summary and head-to-head comparisons\n- arena: All prompts ranked as battlegrounds\n- head-to-head: Direct 1v1 comparison (requires `competitor` param)\n- by-model: Competitor breakdown per AI model\n- threats: Emerging competitor threats and opportunities", "operationId": "get_competitor_data_get_competitor_data_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "brand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias for brand_id", "title": "Brand" }, "description": "Alias for brand_id" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "View mode: summary (default), arena, head-to-head, by-model, threats", "title": "View" }, "description": "View mode: summary (default), arena, head-to-head, by-model, threats" }, { "name": "competitor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Competitor name for head-to-head comparison (required when view=head-to-head)", "title": "Competitor" }, "description": "Competitor name for head-to-head comparison (required when view=head-to-head)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CompetitorDataResponse" }, { "$ref": "#/components/schemas/CompetitorArenaResponse" }, { "$ref": "#/components/schemas/CompetitorH2HResponse" }, { "$ref": "#/components/schemas/CompetitorByModelResponse" }, { "$ref": "#/components/schemas/CompetitorThreatsResponse" }, { "$ref": "#/components/schemas/CompetitorHeatmapResponse" }, { "$ref": "#/components/schemas/CompetitorOverTimeResponse" } ], "title": "Response Get Competitor Data Get Competitor Data Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/competitors/manage": { "post": { "tags": [ "public-api" ], "summary": "Manage Competitor Public", "description": "Manage a brand's competitor lists.\n\n- action='list': read the tracked and hidden competitor names (no competitor needed).\n- action='add': track a competitor by name (appended to brands.competitors).\n- action='remove': untrack a previously added competitor.\n- action='hide': hide a competitor from competitive views.\n- action='unhide': restore a hidden competitor.\n\nCompetitors are identified by name (a domain works too, it is stored as given).\nadd/remove touch the tracked set; hide/unhide touch the hidden set.", "operationId": "manage_competitor_public_competitors_manage_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageCompetitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorManageResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-rankings": { "get": { "tags": [ "public-api" ], "summary": "Get Rankings", "description": "Get competitive ranking data for your brand.\n\nViews:\n- overall (default): Visibility/ranking scores with per-competitor breakdown.\n Reads at most 90 days regardless of `days`; the response carries\n `days_requested`, `days_effective` and a `window_note` when they differ.\n- by-prompt: Rankings per prompt across markets", "operationId": "get_rankings_get_rankings_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "View mode: overall (default), by-prompt", "title": "View" }, "description": "View mode: overall (default), by-prompt" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "description": "Historical period in days, 1-365. view=overall reads at most 90 days and reports the window it actually used in days_effective.", "default": 30, "title": "Days" }, "description": "Historical period in days, 1-365. view=overall reads at most 90 days and reports the window it actually used in days_effective." }, { "name": "include_volume", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Merge search volume data into rankings", "default": false, "title": "Include Volume" }, "description": "Merge search volume data into rankings" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RankingsOverallResponse" }, { "$ref": "#/components/schemas/RankingsByPromptResponse" } ], "title": "Response Get Rankings Get Rankings Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/ai-pages": { "get": { "tags": [ "public-api" ], "summary": "Get Ai Pages", "description": "Get AI Pages status and usage for a brand.\n\nReturns whether AI Pages is enabled, current configuration\n(domain, platform, features, crawlers), and monthly usage stats.\n\nRequires a paid plan with the AI Pages entitlement.", "operationId": "get_ai_pages_ai_pages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrismResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-tags": { "get": { "tags": [ "public-api" ], "summary": "Get Tags Public", "description": "List every prompt tag for a brand, including unused tags.", "operationId": "get_tags_public_get_tags_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagsListResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/manage-prompt-tags": { "post": { "tags": [ "public-api" ], "summary": "Manage Prompt Tags Public", "description": "Create or edit a tag, or add/remove it across one or more prompts.", "operationId": "manage_prompt_tags_public_manage_prompt_tags_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagePromptTagsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagePromptTagsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-prompts": { "get": { "tags": [ "public-api" ], "summary": "List Prompts", "description": "List prompts being tracked for a brand.\n\nOptionally filter by tags using tag_ids (comma-separated UUIDs).", "operationId": "list_prompts_get_prompts_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only return active prompts", "default": false, "title": "Active Only" }, "description": "Only return active prompts" }, { "name": "tag_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated tag UUIDs to filter by", "title": "Tag Ids" }, "description": "Comma-separated tag UUIDs to filter by" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Results per page", "default": 100, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptsListResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Create Prompt", "description": "Create a new prompt for tracking.", "operationId": "create_prompt_get_prompts_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePromptRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptItem" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "public-api" ], "summary": "Update Prompt", "description": "Update an existing prompt.", "operationId": "update_prompt_get_prompts_put", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePromptRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptItem" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-api" ], "summary": "Delete Prompt", "description": "Delete a prompt.", "operationId": "delete_prompt_get_prompts_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "prompt_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Prompt UUID to delete", "title": "Prompt Id" }, "description": "Prompt UUID to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDeleteResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-prompts/suggest": { "post": { "tags": [ "public-api" ], "summary": "Suggest Prompts Api", "description": "Suggest new AI-search prompts to track for a brand.\n\nGenerates generic, buyer-style category queries (never brand names),\ngrounded in the brand's own profile: what it does, its market and\nlanguage, and its competitors. Suggestions that duplicate a prompt the\nbrand already tracks are filtered out, so callers only see fresh ideas.\n\nNothing is created here. These are proposals to review and then add with\nPOST /get-prompts (or the bulk endpoints). Pass an optional `focus` to\nsteer suggestions toward a product line or use-case.", "operationId": "suggest_prompts_api_get_prompts_suggest_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestPromptsApiRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestPromptsApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-models": { "get": { "tags": [ "public-api" ], "summary": "Get Models", "description": "Get visibility breakdown by AI model.", "operationId": "get_models_get_models_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Analysis period in days", "default": 30, "title": "Days" }, "description": "Analysis period in days" }, { "name": "include_trends", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include daily breakdown", "default": false, "title": "Include Trends" }, "description": "Include daily breakdown" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-opportunities": { "get": { "tags": [ "public-api" ], "summary": "Get Opportunities", "description": "Find gaps where your brand should be appearing but isn't.\n\nReturns prompts where competitors appear but your brand doesn't.\n\ncitation_opportunities holds a current per-brand set, not a time series:\nthe generator dedupes on unique_key and rewrites on force, and\nlast_seen_date is never populated. Defaulting to a created_at window\ntherefore hid the whole set once it aged past the window, which is why\nthis endpoint returned an empty list for every brand from 30 Jun 2026\nonward while the app kept showing the same rows. Default to no window and\nfilter on archived, exactly like the app read path in routes/outreach.py.", "operationId": "get_opportunities_get_opportunities_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "Optional. Only return opportunities first found in the last N days. Omit for the brand's current opportunity set, which is what the app shows.", "title": "Days" }, "description": "Optional. Only return opportunities first found in the last N days. Omit for the brand's current opportunity set, which is what the app shows." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Max opportunities to return", "default": 50, "title": "Limit" }, "description": "Max opportunities to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/export": { "get": { "tags": [ "public-api" ], "summary": "Export Data", "description": "Export data in JSON or CSV format.\n\nRequires a paid plan.", "operationId": "export_data_export_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "data_type", "in": "query", "required": true, "schema": { "enum": [ "prompts", "results", "citations", "reports" ], "type": "string", "description": "Type of data to export", "title": "Data Type" }, "description": "Type of data to export" }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "json", "csv" ], "type": "string", "description": "Export format", "default": "json", "title": "Format" }, "description": "Export format" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "description": "For time-based data", "default": 30, "title": "Days" }, "description": "For time-based data" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Max records", "default": 1000, "title": "Limit" }, "description": "Max records" } ], "responses": { "200": { "description": "JSON export or CSV text, selected by the format query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResponse" } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-perception": { "get": { "tags": [ "public-api" ], "summary": "Get Perception", "description": "Get perception data for a brand.\n\nViews:\n- dashboard (default): full perception dashboard \u2014 scores, time series,\n competitor gaps, radar chart data\n- metrics: raw metric_history rows (optionally filter by tracked_brand)\n- narrative: latest positioning summary \u2014 strengths, weaknesses, opportunities\n- story: weekly story / narrative arc payload that drives the Story tab\n- narrative_drift: how the brand's narrative has shifted over `weeks` weeks\n (used by the Goals tab)\n\nRequires a paid plan.", "operationId": "get_perception_get_perception_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "dashboard", "metrics", "narrative", "story", "narrative_drift" ], "type": "string", "description": "View type: dashboard, metrics, narrative, story, or narrative_drift", "default": "dashboard", "title": "View" }, "description": "View type: dashboard, metrics, narrative, story, or narrative_drift" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Number of days of data (dashboard/metrics views)", "default": 90, "title": "Days" }, "description": "Number of days of data (dashboard/metrics views)" }, { "name": "weeks", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 52, "minimum": 1, "description": "Number of weeks for narrative_drift view", "default": 8, "title": "Weeks" }, "description": "Number of weeks for narrative_drift view" }, { "name": "tracked_brand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by specific tracked brand (metrics view only)", "title": "Tracked Brand" }, "description": "Filter by specific tracked brand (metrics view only)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PerceptionDashboardApiResponse" }, { "$ref": "#/components/schemas/PerceptionMetricsApiResponse" }, { "$ref": "#/components/schemas/PerceptionNarrativeApiResponse" }, { "type": "object", "additionalProperties": true } ], "title": "Response Get Perception Get Perception Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Trigger Perception", "description": "Trigger a new perception analysis for a brand.\n\nQueries 4 AI models (GPT-4o, Claude, Gemini, Perplexity) to evaluate\nhow they perceive your brand across 20 metrics.\n\nRequires a paid plan.", "operationId": "trigger_perception_get_perception_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerceptionRunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerceptionRunApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/narratives": { "get": { "tags": [ "public-api" ], "summary": "Get Narratives", "description": "List narratives or get a single narrative detail.\n\nWithout narrative_id: returns all narratives for the brand.\nWith narrative_id: returns single narrative with latest snapshot and correctives.\nUse include=snapshots to embed snapshot history, include=correctives for correctives.\n\nRequires Scale plan.", "operationId": "get_narratives_narratives_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "narrative_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Specific narrative ID for detail view", "title": "Narrative Id" }, "description": "Specific narrative ID for detail view" }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated: snapshots,correctives", "title": "Include" }, "description": "Comma-separated: snapshots,correctives" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Days for snapshot history", "default": 90, "title": "Days" }, "description": "Days for snapshot history" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/NarrativesListApiResponse" }, { "$ref": "#/components/schemas/NarrativeItemApi" } ], "title": "Response Get Narratives Narratives Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Create Narrative Api", "description": "Create a new narrative and trigger the first analysis.\n\nNarratives track how AI models discuss a specific topic related to your brand.\nThe first analysis runs automatically in the background.\n\nRequires Scale plan.", "operationId": "create_narrative_api_narratives_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativeCreateApiRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativeCreateApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "public-api" ], "summary": "Update Narrative Api", "description": "Update a narrative's name, description, keywords, comparison brand, or status.\n\nRequires Scale plan.", "operationId": "update_narrative_api_narratives_patch", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativeUpdateApiRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativeUpdateApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-api" ], "summary": "Delete Narrative Api", "description": "Archive (soft-delete) a narrative. Sets status to \"resolved\".\n\nRequires Scale plan.", "operationId": "delete_narrative_api_narratives_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "narrative_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Narrative ID to archive", "title": "Narrative Id" }, "description": "Narrative ID to archive" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativeDeleteApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/diagnose": { "post": { "tags": [ "public-api" ], "summary": "Run Diagnose Api", "description": "Start a new diagnosis for a search query.\n\nQueries AI models to analyze why your brand does or doesn't appear for\nthis query, then provides recommendations. Poll GET /diagnose?diagnosis_id=X\nfor results.\n\nSubject to monthly usage limits based on your plan.", "operationId": "run_diagnose_api_diagnose_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnoseRunApiRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnoseRunApiResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "public-api" ], "summary": "Get Diagnose Api", "description": "Get diagnosis results, history, or usage.\n\n- diagnosis_id: Returns full diagnosis result (poll until status is completed/failed).\n- view=history: Returns past diagnoses for a brand.\n- view=usage: Returns monthly usage quota.\n\nSubject to monthly usage limits based on your plan.", "operationId": "get_diagnose_api_diagnose_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand UUID (required for history/usage views)", "title": "Brand Id" }, "description": "Brand UUID (required for history/usage views)" }, { "name": "diagnosis_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Diagnosis ID to retrieve results", "title": "Diagnosis Id" }, "description": "Diagnosis ID to retrieve results" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "history", "usage" ], "type": "string" }, { "type": "null" } ], "description": "View type: history or usage", "title": "View" }, "description": "View type: history or usage" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max results for history view", "default": 20, "title": "Limit" }, "description": "Max results for history view" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DiagnoseResultApiResponse" }, { "$ref": "#/components/schemas/DiagnoseHistoryApiResponse" }, { "$ref": "#/components/schemas/DiagnoseUsageApiResponse" } ], "title": "Response Get Diagnose Api Diagnose Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-content-ideas": { "get": { "tags": [ "public-api" ], "summary": "Get Content Ideas Public", "description": "List AI-generated content gap opportunities for a brand.\n\nReturns content ideas ranked by opportunity score, with optional status filtering.\nIdeas are generated periodically by Trakkr's analysis engine.", "operationId": "get_content_ideas_public_get_content_ideas_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Results per page", "default": 50, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "active", "dismissed", "implemented" ], "type": "string" }, { "type": "null" } ], "description": "Filter by status", "title": "Status" }, "description": "Filter by status" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentIdeasPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Refresh Content Ideas Public", "description": "Trigger a refresh of content ideas for a brand.\n\nStarts background regeneration of AI content gap analysis.\nReturns immediately with a status indicator.\n\nRequires a paid plan.", "operationId": "refresh_content_ideas_public_get_content_ideas_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentIdeasRefreshRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentIdeasRefreshResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-reports/{report_id}/download": { "get": { "tags": [ "public-api" ], "summary": "Download Report Public", "description": "Return PDF bytes after API-key and current brand authorization.", "operationId": "download_report_public_get_reports__report_id__download_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Report Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-reports": { "get": { "tags": [ "public-api" ], "summary": "Get Reports Public", "description": "List reports or get a single report detail.\n\nViews:\n- list (default): Paginated report list or single report detail\n- results: Per-prompt and per-model breakdown for a specific report (requires report_id)\n- sentiment: Sentiment distribution and trends\n- mentions_time_series: Mention counts over time", "operationId": "get_reports_public_get_reports_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand UUID (required for listing)", "title": "Brand Id" }, "description": "Brand UUID (required for listing)" }, { "name": "report_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report UUID (for single report detail)", "title": "Report Id" }, "description": "Report UUID (for single report detail)" }, { "name": "report_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by report type", "title": "Report Type" }, "description": "Filter by report type" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status", "title": "Status" }, "description": "Filter by status" }, { "name": "view", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "View mode: list (default), results, sentiment, mentions_time_series", "title": "View" }, "description": "View mode: list (default), results, sentiment, mentions_time_series" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 7, "description": "Historical period (for sentiment and mentions views)", "default": 30, "title": "Days" }, "description": "Historical period (for sentiment and mentions views)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Results per page", "default": 20, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReportsListPublicResponse" }, { "$ref": "#/components/schemas/ReportSinglePublicResponse" }, { "$ref": "#/components/schemas/ReportResultsResponse" }, { "$ref": "#/components/schemas/ReportSentimentResponse" }, { "$ref": "#/components/schemas/ReportMentionsResponse" } ], "title": "Response Get Reports Public Get Reports Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Generate Report Public", "description": "Generate a new AI intelligence report for a brand.\n\nCreates a comprehensive report with visibility metrics, competitive analysis,\nwins/losses, and strategic recommendations. Reports are stored for 30 days.\n\nRequires a paid plan.", "operationId": "generate_report_public_get_reports_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateReportPublicRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateReportPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-crawler": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler", "description": "Get AI crawler analytics for a brand.\n\nRequires the 'crawler' feature entitlement (paid plans, not trials).\n\n- view=dashboard: summary, distribution, time series, top pages, recent activity\n- view=recent: last 100 crawler visits", "operationId": "get_crawler_get_crawler_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "dashboard", "recent" ], "type": "string", "description": "View type", "default": "dashboard", "title": "View" }, "description": "View type" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Number of days (dashboard view, 1-90)", "default": 7, "title": "Days" }, "description": "Number of days (dashboard view, 1-90)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CrawlerDashboardResponse" }, { "$ref": "#/components/schemas/CrawlerRecentResponse" } ], "title": "Response Get Crawler Get Crawler Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/overview": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Overview", "description": "Crawler dashboard overview aligned to the product's hero and chart.", "operationId": "get_crawler_overview_crawler_overview_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "compare_to", "in": "query", "required": false, "schema": { "enum": [ "none", "previous_period" ], "type": "string", "default": "none", "title": "Compare To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerOverviewResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/live": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Live", "description": "Crawler Live tab: activity, top pages, or sessions.", "operationId": "get_crawler_live_crawler_live_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "activity", "pages", "sessions" ], "type": "string", "default": "activity", "title": "View" } }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "intent", "in": "query", "required": false, "schema": { "enum": [ "all", "interaction", "search", "training" ], "type": "string", "default": "all", "title": "Intent" } }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated platform names", "title": "Platform" }, "description": "Comma-separated platform names" }, { "name": "http_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated status groups: 2xx,3xx,4xx,5xx", "title": "Http Status" }, "description": "Comma-separated status groups: 2xx,3xx,4xx,5xx" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort By" } }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "default": "desc", "title": "Sort Dir" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerLiveResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/pages": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Pages", "description": "Crawler Pages tab: pages, paths, and bots.", "operationId": "get_crawler_pages_crawler_pages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "lens", "in": "query", "required": false, "schema": { "enum": [ "pages", "paths", "bots" ], "type": "string", "default": "pages", "title": "Lens" } }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "intent", "in": "query", "required": false, "schema": { "enum": [ "all", "interaction", "search", "training" ], "type": "string", "default": "all", "title": "Intent" } }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated platform names", "title": "Platform" }, "description": "Comma-separated platform names" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "all", "converting", "cited", "crawled", "healthy", "cold" ], "type": "string", "default": "all", "title": "Status" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sort By" } }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "enum": [ "asc", "desc" ], "type": "string", "default": "desc", "title": "Sort Dir" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerPagesResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/page-details": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Page Details", "description": "Crawler page drawer data.", "operationId": "get_crawler_page_details_crawler_page_details_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "page_url", "in": "query", "required": true, "schema": { "type": "string", "title": "Page Url" } }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerDetailResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/path-details": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Path Details", "description": "Crawler path drawer data.", "operationId": "get_crawler_path_details_crawler_path_details_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "path_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Path Id" } }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "intent", "in": "query", "required": false, "schema": { "enum": [ "all", "interaction", "search", "training" ], "type": "string", "default": "all", "title": "Intent" } }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "all", "converting", "cited", "crawled", "healthy", "cold" ], "type": "string", "default": "all", "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerDetailResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/bot-details": { "get": { "tags": [ "public-api" ], "summary": "Get Crawler Bot Details", "description": "Crawler bot drawer data.", "operationId": "get_crawler_bot_details_crawler_bot_details_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "bot_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Normalized bot display name", "title": "Bot Name" }, "description": "Normalized bot display name" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "intent", "in": "query", "required": false, "schema": { "enum": [ "all", "interaction", "search", "training" ], "type": "string", "default": "all", "title": "Intent" } }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "all", "converting", "cited", "crawled", "healthy", "cold" ], "type": "string", "default": "all", "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerDetailResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/access": { "get": { "tags": [ "public-api" ], "summary": "Get Public Crawler Access", "description": "Crawler Access tab payload.", "operationId": "get_public_crawler_access_crawler_access_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Public Crawler Access Crawler Access Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/crawler/access": { "get": { "tags": [ "public-api" ], "summary": "Get Public Crawler Access", "description": "Crawler Access tab payload.", "operationId": "get_public_crawler_access_api_v1_crawler_access_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Public Crawler Access Api V1 Crawler Access Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawler/access/preview-fix": { "post": { "tags": [ "public-api" ], "summary": "Preview Public Crawler Fix", "description": "Preview a crawler access fix without applying it.", "operationId": "preview_public_crawler_fix_crawler_access_preview_fix_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerAccessPreviewFixRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Preview Public Crawler Fix Crawler Access Preview Fix Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/crawler/verification-ping": { "post": { "tags": [ "public-api" ], "summary": "Trigger Public Crawler Verification Ping", "description": "Send the same verification ping available in the crawler dashboard.", "operationId": "trigger_public_crawler_verification_ping_crawler_verification_ping_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_trigger_public_crawler_verification_ping_crawler_verification_ping_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Trigger Public Crawler Verification Ping Crawler Verification Ping Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/crawler/verification-ping": { "post": { "tags": [ "public-api" ], "summary": "Trigger Public Crawler Verification Ping", "description": "Send the same verification ping available in the crawler dashboard.", "operationId": "trigger_public_crawler_verification_ping_api_v1_crawler_verification_ping_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_trigger_public_crawler_verification_ping_api_v1_crawler_verification_ping_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Trigger Public Crawler Verification Ping Api V1 Crawler Verification Ping Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/mcp/crawler/verification-ping": { "post": { "tags": [ "public-api" ], "summary": "Trigger Public Crawler Verification Ping", "description": "Send the same verification ping available in the crawler dashboard.", "operationId": "trigger_public_crawler_verification_ping_mcp_crawler_verification_ping_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body_trigger_public_crawler_verification_ping_mcp_crawler_verification_ping_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Trigger Public Crawler Verification Ping Mcp Crawler Verification Ping Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/crawler/submit-to-search": { "post": { "tags": [ "public-api" ], "summary": "Submit Public Crawler To Search", "description": "Submit crawler pages to Bing IndexNow, matching the Access tab action.", "operationId": "submit_public_crawler_to_search_crawler_submit_to_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerSubmitToSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Submit Public Crawler To Search Crawler Submit To Search Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/crawler/submit-to-search": { "post": { "tags": [ "public-api" ], "summary": "Submit Public Crawler To Search", "description": "Submit crawler pages to Bing IndexNow, matching the Access tab action.", "operationId": "submit_public_crawler_to_search_api_v1_crawler_submit_to_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlerSubmitToSearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Submit Public Crawler To Search Api V1 Crawler Submit To Search Post" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/crawler/submit-to-search/status": { "get": { "tags": [ "public-api" ], "summary": "Get Public Crawler Submit Status", "description": "Get submit-to-search status, matching the Access tab summary/status surface.", "operationId": "get_public_crawler_submit_status_crawler_submit_to_search_status_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "urls", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated URLs to check", "title": "Urls" }, "description": "Comma-separated URLs to check" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "pending", "success", "failed" ], "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Public Crawler Submit Status Crawler Submit To Search Status Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/crawler/submit-to-search/status": { "get": { "tags": [ "public-api" ], "summary": "Get Public Crawler Submit Status", "description": "Get submit-to-search status, matching the Access tab summary/status surface.", "operationId": "get_public_crawler_submit_status_api_v1_crawler_submit_to_search_status_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "range_preset", "in": "query", "required": false, "schema": { "enum": [ "24h", "7d", "30d", "90d", "custom" ], "type": "string", "default": "30d", "title": "Range Preset" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, { "name": "urls", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated URLs to check", "title": "Urls" }, "description": "Comma-separated URLs to check" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "pending", "success", "failed" ], "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Get Public Crawler Submit Status Api V1 Crawler Submit To Search Status Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-brands/markets": { "post": { "tags": [ "public-api" ], "summary": "Add Brand Market", "description": "Add a market (geographic region) to a brand.\n\nSubject to market limits based on your plan.", "operationId": "add_brand_market_get_brands_markets_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMarketRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketItem" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-api" ], "summary": "Remove Brand Market", "description": "Remove a market from a brand (soft-delete).\nCannot remove the primary market.", "operationId": "remove_brand_market_get_brands_markets_delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "market_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Market UUID to remove", "title": "Market Id" }, "description": "Market UUID to remove" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDeleteResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-brands/aliases": { "put": { "tags": [ "public-api" ], "summary": "Update Brand Aliases", "description": "Update brand aliases (alternate names aggregated into visibility).", "operationId": "update_brand_aliases_get_brands_aliases_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAliasesApiRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandAliasesResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-brands/location": { "put": { "tags": [ "public-api" ], "summary": "Update Brand Location", "description": "Set a brand's primary geographic market (country, optionally region/city).\n\nThis pins the brand's home market so competitor analysis and AI search\nresults are measured against the right region instead of defaulting toward\nglobal/US-skewed results. Updating the primary market reuses the existing\nprimary slot \u2014 it does not consume an extra-market add-on.", "operationId": "update_brand_location_get_brands_location_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandLocationRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBrandLocationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/webhooks": { "post": { "tags": [ "public-api" ], "summary": "Create Webhook", "description": "Register a new webhook endpoint to receive event notifications.\n\nSupported events: visibility_changed, report_completed,\ncompetitor_added, citation_gained, citation_lost.", "operationId": "create_webhook_webhooks_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "public-api" ], "summary": "List Webhooks", "description": "List all webhooks for the authenticated user, optionally filtered by brand.", "operationId": "list_webhooks_webhooks_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by brand UUID", "title": "Brand Id" }, "description": "Filter by brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{webhook_id}": { "get": { "tags": [ "public-api" ], "summary": "Get Webhook", "description": "Retrieve a single webhook by ID.", "operationId": "get_webhook_webhooks__webhook_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-api" ], "summary": "Delete Webhook", "description": "Delete a webhook.", "operationId": "delete_webhook_webhooks__webhook_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDeleteResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{webhook_id}/test": { "post": { "tags": [ "public-api" ], "summary": "Test Webhook Endpoint", "description": "Send a test event to a webhook to verify it's working.", "operationId": "test_webhook_endpoint_webhooks__webhook_id__test_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-prompts/bulk": { "post": { "tags": [ "public-api" ], "summary": "Bulk Create Prompts", "description": "Bulk create up to 50 prompts in a single request.", "operationId": "bulk_create_prompts_get_prompts_bulk_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreatePromptsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreatePromptsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] }, "delete": { "tags": [ "public-api" ], "summary": "Bulk Delete Prompts", "description": "Bulk delete up to 50 prompts in a single request.", "operationId": "bulk_delete_prompts_get_prompts_bulk_delete", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletePromptsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeletePromptsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-prompts/activate": { "patch": { "tags": [ "public-api" ], "summary": "Bulk Activate Prompts", "description": "Activate multiple prompts.", "operationId": "bulk_activate_prompts_get_prompts_activate_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActivateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActivateResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-prompts/deactivate": { "patch": { "tags": [ "public-api" ], "summary": "Bulk Deactivate Prompts", "description": "Deactivate multiple prompts.", "operationId": "bulk_deactivate_prompts_get_prompts_deactivate_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActivateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActivateResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-prompts/rerun": { "post": { "tags": [ "public-api" ], "summary": "Rerun Prompt", "description": "Retired compatibility endpoint for the unsupported single-prompt rerun.", "operationId": "rerun_prompt_get_prompts_rerun_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerunPromptRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerunPromptResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "410": { "description": "Single-prompt reruns are no longer supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerunPromptResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "deprecated": true, "security": [ { "HTTPBearer": [] } ] } }, "/get-reports/compare": { "post": { "tags": [ "public-api" ], "summary": "Compare Reports", "description": "Compare visibility metrics between two time periods.", "operationId": "compare_reports_get_reports_compare_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportCompareRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportCompareResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/traffic/status": { "get": { "tags": [ "public-api" ], "summary": "Get Traffic Status", "description": "Check if live traffic tracking is connected for a brand.", "operationId": "get_traffic_status_traffic_status_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficStatusResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/traffic/report": { "get": { "tags": [ "public-api" ], "summary": "Get Traffic Report", "description": "Get AI traffic analytics report for a brand.", "operationId": "get_traffic_report_traffic_report_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 7, "description": "Period in days", "default": 30, "title": "Days" }, "description": "Period in days" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficReportResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/traffic/visitors": { "get": { "tags": [ "public-api" ], "summary": "Get Traffic Visitors", "description": "Get recent AI visitors for a brand.", "operationId": "get_traffic_visitors_traffic_visitors_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficVisitorsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/traffic/conversions": { "get": { "tags": [ "public-api" ], "summary": "Get Traffic Conversions", "description": "Get conversion values for a brand.", "operationId": "get_traffic_conversions_traffic_conversions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionValuesResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "public-api" ], "summary": "Set Traffic Conversion", "description": "Set a conversion value for a specific event.", "operationId": "set_traffic_conversion_traffic_conversions_post", "security": [ { "HTTPBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConversionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficConversionMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/traffic/conversions/{event_name}": { "delete": { "tags": [ "public-api" ], "summary": "Delete Traffic Conversion", "description": "Delete a conversion value.", "operationId": "delete_traffic_conversion_traffic_conversions__event_name__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "event_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Event Name" } }, { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficConversionMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-actions": { "get": { "tags": [ "public-api" ], "summary": "Get Actions Public", "description": "List actions (recommendations) for a brand from the unified actions queue.\n\nThis is the canonical \"what should the brand do\" surface \u2014 every signal in\nTrakkr (audit, crawler, prompts, citations, competitors, traffic, reddit,\ndiagnose) gets synthesized into this queue with title, description, detail,\nfirst_step, effort, impact, priority_score, action_data (the raw supporting\nevidence), and a deep_link. Actions that carry them also return family,\npage_id, page_url, and result (the measured before/after outcome). The\ndeprecated proof alias remains for existing integrations.\n\nFor an \"AI search technical audit\" view, filter:\n source=site_audit,crawler_monitoring AND category=technical\n\nRead-only. Synthesis runs server-side on a cooldown; this endpoint never\ntriggers generation.", "operationId": "get_actions_public_get_actions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by action status. Use 'open' (default) for the live queue (pending + in_progress + snoozed), 'active' to include completed, or pass a single literal: pending, in_progress, completed, dismissed, snoozed.", "default": "open", "title": "Status" }, "description": "Filter by action status. Use 'open' (default) for the live queue (pending + in_progress + snoozed), 'active' to include completed, or pass a single literal: pending, in_progress, completed, dismissed, snoozed." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated categories: content, technical, competitive, optimization, citation, setup, reddit, diagnose.", "title": "Category" }, "description": "Comma-separated categories: content, technical, competitive, optimization, citation, setup, reddit, diagnose." }, { "name": "action_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single action_type (e.g. 'add_llms_txt')", "title": "Action Type" }, "description": "Filter to a single action_type (e.g. 'add_llms_txt')" }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by source: site_audit, crawler_monitoring, prompt_monitoring, citation_monitoring, diagnose, competitor_tracking, content_ideas, traffic_analytics, reddit, setup, manual, ai_synthesizer.", "title": "Source" }, "description": "Filter by source: site_audit, crawler_monitoring, prompt_monitoring, citation_monitoring, diagnose, competitor_tracking, content_ideas, traffic_analytics, reddit, setup, manual, ai_synthesizer." }, { "name": "lens", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional product-lens filter (e.g. 'crawler' for crawler-tab view).", "title": "Lens" }, "description": "Optional product-lens filter (e.g. 'crawler' for crawler-tab view)." }, { "name": "quick_win", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "If true, only return high-impact / low-effort actions.", "title": "Quick Win" }, "description": "If true, only return high-impact / low-effort actions." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Text search across title, description, source, action_type.", "title": "Search" }, "description": "Text search across title, description, source, action_type." }, { "name": "url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to actions scoped to this URL or path.", "title": "Url" }, "description": "Filter to actions scoped to this URL or path." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "description": "priority_score | created_at | updated_at", "default": "priority_score", "title": "Sort By" }, "description": "priority_score | created_at | updated_at" }, { "name": "sort_dir", "in": "query", "required": false, "schema": { "type": "string", "description": "asc or desc", "default": "desc", "title": "Sort Dir" }, "description": "asc or desc" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Results per page", "default": 50, "title": "Limit" }, "description": "Results per page" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-action-stats": { "get": { "tags": [ "public-api" ], "summary": "Get Action Stats Public", "description": "Aggregate action counts for a brand \u2014 totals by status, plus breakdowns\nby category, action_type, and source.\n\nUse this to understand the shape of the queue before paging through it\n(e.g. \"how many open technical actions are there?\").", "operationId": "get_action_stats_public_get_action_stats_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionStatsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/manage-action": { "post": { "tags": [ "public-api" ], "summary": "Manage Action Public", "description": "Act on a single recommendation in the brand action queue.\n\nPair with /get-actions (which is read-only): list the queue, then move one\naction with this endpoint. One explicit verb per call, never a destructive\ndefault:\n complete | dismiss | reopen | start | snooze | unsnooze |\n pin | unpin | assign | note\n\nsnooze needs snooze_until (ISO date or datetime, must be in the future).\nassign needs assignee (a brand member user id). note needs note text.\nEditor access to the brand is required, the same bar the in-product Actions\npage enforces.", "operationId": "manage_action_public_manage_action_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageActionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageActionResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/get-audits": { "get": { "tags": [ "public-api" ], "summary": "Get Audits Public", "description": "List site audits for a brand, or fetch one by ID.\n\nEach audit is a snapshot of the brand's site at a point in time, with\nissue counts, an overall score, and the detected CMS platform. To go\ndeeper, call /get-audit-findings with the audit_id (or omit it to use\nthe latest complete audit).\n\nRead-only. Audits are scheduled server-side and cannot be triggered here.", "operationId": "get_audits_public_get_audits_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "audit_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional audit UUID to fetch a single record", "title": "Audit Id" }, "description": "Optional audit UUID to fetch a single record" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by audit status (e.g. 'complete')", "title": "Status" }, "description": "Filter by audit status (e.g. 'complete')" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max audits to return", "default": 20, "title": "Limit" }, "description": "Max audits to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditsListResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-audit-findings": { "get": { "tags": [ "public-api" ], "summary": "Get Audit Findings Public", "description": "Return the audit issues + flagged pages for a brand's latest (or specified)\naudit. This is the \"what's wrong\" surface for an AI-search technical audit,\nmirroring the data the Optimize page's Findings and Pages tabs render from.\n\nDismissals are applied: a check the customer marked intentional in Optimize\nreads as status='ignored' here rather than open, and stays that way across\nre-scans. Pass issue_status=ignored to list them.\n\nReturns status='no_audit_yet' if the brand has no completed audit yet.\n\nRead-only. Never triggers an audit or any analysis.", "operationId": "get_audit_findings_public_get_audit_findings_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "audit_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Specific audit UUID. Defaults to the latest complete audit for the brand.", "title": "Audit Id" }, "description": "Specific audit UUID. Defaults to the latest complete audit for the brand." }, { "name": "severity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated severities: critical, high, medium, low.", "default": "critical,high", "title": "Severity" }, "description": "Comma-separated severities: critical, high, medium, low." }, { "name": "issue_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated issue statuses: open, in_progress, fixed, ignored.", "default": "open,in_progress", "title": "Issue Status" }, "description": "Comma-separated issue statuses: open, in_progress, fixed, ignored." }, { "name": "check_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single check (substring match).", "title": "Check Name" }, "description": "Filter to a single check (substring match)." }, { "name": "page_url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter issues whose affected_urls contain this URL substring.", "title": "Page Url" }, "description": "Filter issues whose affected_urls contain this URL substring." }, { "name": "page_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter audit_pages by page_type.", "title": "Page Type" }, "description": "Filter audit_pages by page_type." }, { "name": "url_pattern", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter audit_pages by URL substring.", "title": "Url Pattern" }, "description": "Filter audit_pages by URL substring." }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 0 }, { "type": "null" } ], "description": "Min technical_score for pages.", "title": "Min Score" }, "description": "Min technical_score for pages." }, { "name": "max_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 0 }, { "type": "null" } ], "description": "Max technical_score for pages.", "title": "Max Score" }, "description": "Max technical_score for pages." }, { "name": "issues_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Max issues to return.", "default": 20, "title": "Issues Limit" }, "description": "Max issues to return." }, { "name": "pages_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Max pages to return.", "default": 20, "title": "Pages Limit" }, "description": "Max pages to return." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditFindingsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-page-analyses": { "get": { "tags": [ "public-api" ], "summary": "Get Page Analyses Public", "description": "Read cached deep page analyses for a brand.\n\nTwo modes:\n\n1. **Listing** (no `url`): returns recent analyses with URL, scores,\n page_type, and stale flag. Useful to see which pages have been\n analyzed and which still need work.\n\n2. **Detail** (with `url`): returns the full cached analysis for one\n URL \u2014 AI diagnosis, citation verdict, failed checks, ready-to-paste\n schema, entities, bot visibility. Returns 404 if no cached analysis\n exists (deliberately \u2014 this endpoint never triggers a new analysis\n to avoid uncontrolled LLM costs).", "operationId": "get_page_analyses_public_get_page_analyses_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "If provided, return the deep analysis for this URL (404 if no cached analysis).", "title": "Url" }, "description": "If provided, return the deep analysis for this URL (404 if no cached analysis)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Max analyses to return when listing.", "default": 20, "title": "Limit" }, "description": "Max analyses to return when listing." }, { "name": "max_age_days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "description": "When fetching by URL, only return analyses newer than this.", "default": 30, "title": "Max Age Days" }, "description": "When fetching by URL, only return analyses newer than this." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PageAnalysesListResponse" }, { "$ref": "#/components/schemas/PageAnalysisDetailResponse" } ], "title": "Response Get Page Analyses Public Get Page Analyses Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/research/runs": { "get": { "tags": [ "public-api" ], "summary": "List Research Runs Public", "description": "List prompt research runs for a brand (newest first).\n\nReturns the same summary fields the in-app /research history surfaces:\nvisibility score, mention rate, position metrics, top competitors, and\nsnapshot topic where applicable.", "operationId": "list_research_runs_public_research_runs_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "report_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by 'full_research' or 'topic_snapshot'. Omit for both.", "title": "Report Type" }, "description": "Filter by 'full_research' or 'topic_snapshot'. Omit for both." }, { "name": "ready_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true (default), only return runs that finished successfully.", "default": true, "title": "Ready Only" }, "description": "If true (default), only return runs that finished successfully." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunsListResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/research/runs/{run_id}": { "get": { "tags": [ "public-api" ], "summary": "Get Research Run Public", "description": "Get a single prompt research run with the full analytics payload.\n\nIncludes every field exposed in the in-app /research view: visibility,\nposition_distribution, competitors_breakdown, intent_breakdown,\nfocus_area_breakdown, topic_breakdown, insights (best/missed prompts),\nand the per-prompt results array (paginated via results_limit/offset).", "operationId": "get_research_run_public_research_runs__run_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "results_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Max per-prompt results to return. Default 100 (full payload is often 500+).", "default": 100, "title": "Results Limit" }, "description": "Max per-prompt results to return. Default 100 (full payload is often 500+)." }, { "name": "results_offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset into the results array.", "default": 0, "title": "Results Offset" }, "description": "Pagination offset into the results array." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunDetailResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/research/latest": { "get": { "tags": [ "public-api" ], "summary": "Get Latest Research Run Public", "description": "Get the most recent ready prompt research run for a brand.\n\nThis is the canonical 'what does my latest research show' endpoint \u2014\nreturns the same payload as /research/runs/{id} for the newest completed\nrun. Falls back through the last 10 candidates to skip repair placeholders.", "operationId": "get_latest_research_run_public_research_latest_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "report_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by 'full_research' or 'topic_snapshot'. Omit for the most recent of either.", "title": "Report Type" }, "description": "Filter by 'full_research' or 'topic_snapshot'. Omit for the most recent of either." }, { "name": "results_limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Results Limit" } }, { "name": "results_offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Results Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunDetailResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/research/snapshot-credits": { "get": { "tags": [ "public-api" ], "summary": "Get Research Snapshot Credits Public", "description": "Get the brand's topic snapshot credit usage for the current month.\n\nReflects the same Trial 1 / Growth 5 / Scale 5 monthly limits (per active\nbrand) that gate the in-app /research snapshot UI.", "operationId": "get_research_snapshot_credits_public_research_snapshot_credits_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchSnapshotCreditsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/research/snapshot": { "post": { "tags": [ "public-api" ], "summary": "Run Research Snapshot Public", "description": "Trigger a topic snapshot research run.\n\nGenerates 50 focused prompts on the supplied topic and runs them through\nthe same pipeline as the in-app /research snapshot feature. Consumes one\nof the brand's monthly snapshot credits (Trial 1 / Growth 5 / Scale 5, per\nactive brand). The brand must be active (tracking on).\n\nSnapshots typically take 3-5 minutes. Use GET /research/runs to poll for\nthe completed payload, or GET /research/latest?report_type=topic_snapshot\nto fetch the most recent one.", "operationId": "run_research_snapshot_public_research_snapshot_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSnapshotPublicRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSnapshotPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/reddit": { "get": { "tags": [ "public-api" ], "summary": "Get Reddit Public", "description": "Reddit monitoring data.\n\nViews:\n- overview: connection state, weekly hero stats, recent opportunities\n- feed: thread feed for monitored subreddits\n- opportunities: actionable threads (low-effort thread engagement)\n- thread: full detail for a single thread (requires thread_id)\n- subreddits: monitored subreddits for this brand\n- triggers: keyword triggers for this brand\n- analytics: insights tab payload (volume + breakdowns + competitors)", "operationId": "get_reddit_public_reddit_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "overview", "feed", "opportunities", "thread", "subreddits", "triggers", "analytics" ], "type": "string", "description": "View mode", "default": "overview", "title": "View" }, "description": "View mode" }, { "name": "thread_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread UUID (required for view=thread)", "title": "Thread Id" }, "description": "Thread UUID (required for view=thread)" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "description": "Lookback window in days", "default": 30, "title": "Days" }, "description": "Lookback window in days" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 30, "title": "Page Size" } }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "newest|comments|citation|score", "title": "Sort" }, "description": "newest|comments|citation|score" }, { "name": "subreddit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated subreddit names to filter", "title": "Subreddit" }, "description": "Comma-separated subreddit names to filter" }, { "name": "mention_type", "in": "query", "required": false, "schema": { "type": "string", "description": "all|own|competitor|both|none", "default": "all", "title": "Mention Type" }, "description": "all|own|competitor|both|none" }, { "name": "min_citation_score", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "default": 0, "title": "Min Citation Score" } }, { "name": "max_citation_score", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 0, "default": 100, "title": "Max Citation Score" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "keyword", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Trigger-keyword filter (opportunities view)", "title": "Keyword" }, "description": "Trigger-keyword filter (opportunities view)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "all|open|responded (opportunities view)", "default": "all", "title": "Status" }, "description": "all|open|responded (opportunities view)" }, { "name": "include_dismissed", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include dismissed opportunities", "default": false, "title": "Include Dismissed" }, "description": "Include dismissed opportunities" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reddit/subreddits": { "post": { "tags": [ "public-api" ], "summary": "Reddit Add Subreddit Public", "description": "Add a monitored subreddit for a brand.", "operationId": "reddit_add_subreddit_public_reddit_subreddits_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditSubredditAddRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/reddit/subreddits/{subreddit_id}": { "delete": { "tags": [ "public-api" ], "summary": "Reddit Remove Subreddit Public", "description": "Remove a monitored subreddit.", "operationId": "reddit_remove_subreddit_public_reddit_subreddits__subreddit_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "subreddit_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Subreddit Id" } }, { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reddit/triggers": { "post": { "tags": [ "public-api" ], "summary": "Reddit Add Trigger Public", "description": "Add a keyword trigger for a brand.", "operationId": "reddit_add_trigger_public_reddit_triggers_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditTriggerAddRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/reddit/triggers/{trigger_id}": { "delete": { "tags": [ "public-api" ], "summary": "Reddit Remove Trigger Public", "description": "Remove a keyword trigger.", "operationId": "reddit_remove_trigger_public_reddit_triggers__trigger_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Trigger Id" } }, { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reddit/opportunities/{opportunity_id}/dismiss": { "post": { "tags": [ "public-api" ], "summary": "Reddit Dismiss Opportunity Public", "description": "Dismiss (or restore) a Reddit opportunity.", "operationId": "reddit_dismiss_opportunity_public_reddit_opportunities__opportunity_id__dismiss_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "opportunity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Opportunity Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditOpportunityDismissRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reddit/opportunities/{opportunity_id}/respond": { "post": { "tags": [ "public-api" ], "summary": "Reddit Mark Responded Public", "description": "Mark a Reddit opportunity as responded to.", "operationId": "reddit_mark_responded_public_reddit_opportunities__opportunity_id__respond_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "opportunity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Opportunity Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditOpportunityRespondRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/reddit/scan": { "post": { "tags": [ "public-api" ], "summary": "Reddit Scan Public", "description": "Queue a Reddit scan for a brand.\n\nThis path is also used by the logged-in app. public_api_router is mounted\nbefore reddit_router, so accept both public API keys and Supabase JWTs here.", "operationId": "reddit_scan_public_reddit_scan_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditScanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditMutationResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/workflows": { "get": { "tags": [ "public-api" ], "summary": "Get Workflows Public", "description": "Workflow read access.\n\nViews:\n- list: paginated workflows for a brand\n- get: single workflow detail (requires workflow_id)\n- runs: recent workflow_runs for a workflow (workflow_id) OR for a brand\n (brand_id + optional trigger_types filter)\n- run_detail: single run including action logs (requires run_id)\n- templates: list of available workflow templates", "operationId": "get_workflows_public_workflows_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Brand UUID (required for list/runs views)", "title": "Brand Id" }, "description": "Brand UUID (required for list/runs views)" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "list", "get", "runs", "run_detail", "templates" ], "type": "string", "default": "list", "title": "View" } }, { "name": "workflow_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workflow UUID (required for get/runs views)", "title": "Workflow Id" }, "description": "Workflow UUID (required for get/runs views)" }, { "name": "run_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Run UUID (required for run_detail view)", "title": "Run Id" }, "description": "Run UUID (required for run_detail view)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status (list/runs views)", "title": "Status" }, "description": "Filter by status (list/runs views)" }, { "name": "trigger_types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated trigger types", "title": "Trigger Types" }, "description": "Comma-separated trigger types" }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 90, "minimum": 1 }, { "type": "null" } ], "description": "Lookback window for runs views", "title": "Days" }, "description": "Lookback window for runs views" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workflows/{workflow_id}": { "patch": { "tags": [ "public-api" ], "summary": "Patch Workflow Public", "description": "Pause, resume, or soft-delete a workflow.", "operationId": "patch_workflow_public_workflows__workflow_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStatusPatchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "public-api" ], "summary": "Delete Workflow Public", "description": "Soft-delete a workflow.", "operationId": "delete_workflow_public_workflows__workflow_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/workflows/{workflow_id}": { "delete": { "tags": [ "public-api" ], "summary": "Delete Workflow Public", "description": "Soft-delete a workflow.", "operationId": "delete_workflow_public_api_v1_workflows__workflow_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workflows/from-template": { "post": { "tags": [ "public-api" ], "summary": "Create Workflow From Template Public", "description": "Create a new workflow from a template (recipients/channels start empty).", "operationId": "create_workflow_from_template_public_workflows_from_template_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowFromTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/notifications": { "get": { "tags": [ "public-api" ], "summary": "Get Notifications Public", "description": "User-scoped notification inbox for the API key owner.\n\nViews:\n- list (default): paginated notifications with total + unread count\n- unread_count: just the unread badge number", "operationId": "get_notifications_public_notifications_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "list", "unread_count" ], "type": "string", "default": "list", "title": "View" } }, { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by brand UUID", "title": "Brand Id" }, "description": "Filter by brand UUID" }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by event_type (e.g. visibility_drop)", "title": "Event Type" }, "description": "Filter by event_type (e.g. visibility_drop)" }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Unread Only" } }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 180, "minimum": 1 }, { "type": "null" } ], "description": "Lookback window in days", "title": "Days" }, "description": "Lookback window in days" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/notifications": { "get": { "tags": [ "public-api" ], "summary": "Get Notifications Public", "description": "User-scoped notification inbox for the API key owner.\n\nViews:\n- list (default): paginated notifications with total + unread count\n- unread_count: just the unread badge number", "operationId": "get_notifications_public_api_v1_notifications_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "list", "unread_count" ], "type": "string", "default": "list", "title": "View" } }, { "name": "brand_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by brand UUID", "title": "Brand Id" }, "description": "Filter by brand UUID" }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by event_type (e.g. visibility_drop)", "title": "Event Type" }, "description": "Filter by event_type (e.g. visibility_drop)" }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Unread Only" } }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 180, "minimum": 1 }, { "type": "null" } ], "description": "Lookback window in days", "title": "Days" }, "description": "Lookback window in days" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/notifications/read": { "post": { "tags": [ "public-api" ], "summary": "Mark Notifications Read Public", "description": "Mark notifications as read (specific IDs or all).", "operationId": "mark_notifications_read_public_notifications_read_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsMarkReadRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsReadResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/notifications/read": { "post": { "tags": [ "public-api" ], "summary": "Mark Notifications Read Public", "description": "Mark notifications as read (specific IDs or all).", "operationId": "mark_notifications_read_public_api_v1_notifications_read_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsMarkReadRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsReadResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/content/knowledge": { "get": { "tags": [ "public-api" ], "summary": "Get Content Knowledge Public", "description": "Knowledge base data for a brand.\n\nViews:\n- sources (default): list every knowledge source with status + chunk counts\n- stats: aggregate counts (total_sources, ready_sources, total_chunks, by_type)", "operationId": "get_content_knowledge_public_content_knowledge_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "sources", "stats", "list" ], "type": "string", "default": "sources", "title": "View" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentKnowledgePublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/content/articles": { "get": { "tags": [ "public-api" ], "summary": "Get Content Articles Public", "description": "Articles for a brand.\n\nViews:\n- list (default): paginated list with title, status, scores\n- detail: full article including content (requires article_id)", "operationId": "get_content_articles_public_content_articles_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "list", "detail", "get" ], "type": "string", "default": "list", "title": "View" } }, { "name": "article_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article UUID (required for view=detail)", "title": "Article Id" }, "description": "Article UUID (required for view=detail)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter: draft|review|ready|published", "title": "Status" }, "description": "Filter: draft|review|ready|published" }, { "name": "standalone_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Exclude campaign articles", "default": false, "title": "Standalone Only" }, "description": "Exclude campaign articles" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ContentArticlesPublicResponse" }, { "type": "object", "additionalProperties": true } ], "title": "Response Get Content Articles Public Content Articles Get" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/content/writing-style": { "get": { "tags": [ "public-api" ], "summary": "Get Content Writing Style Public", "description": "Writing style profile + samples for a brand.\n\nViews:\n- profile (default): synthesised style profile (tone, vocab, structure)\n- samples: list of writing samples that fed the profile", "operationId": "get_content_writing_style_public_content_writing_style_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "view", "in": "query", "required": false, "schema": { "enum": [ "profile", "samples" ], "type": "string", "default": "profile", "title": "View" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentWritingStylePublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/content/knowledge/sources/text": { "post": { "tags": [ "public-api" ], "summary": "Add Content Knowledge Text Public", "description": "Add a raw-text source to a brand's knowledge base.\n\nProcessing is async: the source returns with status='pending' and is chunked\nand embedded in the background. Poll GET /content/knowledge?view=sources for\nstatus (pending -> ready/error) and chunk counts.", "operationId": "add_content_knowledge_text_public_content_knowledge_sources_text_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKnowledgeTextRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutationPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/content/knowledge/sources/url": { "post": { "tags": [ "public-api" ], "summary": "Add Content Knowledge Url Public", "description": "Ingest a web page into a brand's knowledge base.\n\nThe page is fetched and its text extracted server-side, then processed\nasync (status='pending' -> ready/error). Poll GET /content/knowledge.", "operationId": "add_content_knowledge_url_public_content_knowledge_sources_url_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKnowledgeUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutationPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/content/knowledge/sources/{source_id}": { "delete": { "tags": [ "public-api" ], "summary": "Delete Content Knowledge Source Public", "description": "Delete a knowledge source and its vectors. The delegated handler verifies\nbrand access from the source's own brand_id.", "operationId": "delete_content_knowledge_source_public_content_knowledge_sources__source_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutationPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/content/knowledge/sources/{source_id}/reprocess": { "post": { "tags": [ "public-api" ], "summary": "Reprocess Content Knowledge Source Public", "description": "Re-chunk and re-embed a knowledge source (recover from an error or refresh\nafter fixing it). Brand access is verified from the source's brand_id.", "operationId": "reprocess_content_knowledge_source_public_content_knowledge_sources__source_id__reprocess_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutationPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/content/articles/generate": { "post": { "tags": [ "public-api" ], "summary": "Generate Content Article Public", "description": "Kick off article generation. Returns immediately with status='queued';\ngeneration runs in the background and consumes one article credit (402 if\nthe brand owner has none left). Poll GET /content/articles?view=detail until\nstatus='draft'. This never publishes: the result is a draft to review.", "operationId": "generate_content_article_public_content_articles_generate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicGenerateArticleRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentMutationPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agency/brand-groups": { "get": { "tags": [ "public-api" ], "summary": "List Brand Groups Public", "description": "List brand groups owned by the API key holder's team.\n\nReturns each group with name, brand_count, client_count and the list of\nbrands inside it. Useful for agencies organising portfolios of brands.", "operationId": "list_brand_groups_public_agency_brand_groups_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandGroupsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agency/compare-brands": { "post": { "tags": [ "public-api" ], "summary": "Compare Brands Public", "description": "Side-by-side metrics for 2-10 brands the caller has access to.\n\nReturns for each brand: latest visibility + 30d delta, top open action count,\ntotal citations in window, and headline competitor. Useful for agency\n\"compare clients\" or \"you vs them\" workflows.", "operationId": "compare_brands_public_agency_compare_brands_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareBrandsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareBrandsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/agency/portfolio-actions": { "get": { "tags": [ "public-api" ], "summary": "Get Portfolio Actions Public", "description": "Cross-brand action queue for the caller's portfolio.\n\nReturns highest-impact open actions across every brand the API key holder\ncan access. Each action includes the brand name + id so an agency operator\ncan prioritise work across clients in one view.", "operationId": "get_portfolio_actions_public_agency_portfolio_actions_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to brands in this group", "title": "Group Id" }, "description": "Restrict to brands in this group" }, { "name": "quick_win", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Quick Win" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioActionsPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-opportunity-pool": { "get": { "tags": [ "public-api" ], "summary": "Get Opportunity Pool Public", "description": "Suggestions waiting on a decision.\n\nNOT the same object as `/get-opportunities`, which serves\n`citation_opportunities`. This is the unified pool every recommendation\nsystem now writes to.", "operationId": "get_opportunity_pool_public_get_opportunity_pool_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "family", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "fix|refresh|create|earn|discuss|optimize|setup|play", "title": "Family" }, "description": "fix|refresh|create|earn|discuss|optimize|setup|play" }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated kinds", "title": "Kind" }, "description": "Comma-separated kinds" }, { "name": "impact", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "low|medium|high", "title": "Impact" }, "description": "low|medium|high" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from meta.next_cursor", "title": "Cursor" }, "description": "Opaque cursor from meta.next_cursor" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityPoolResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/commit-opportunity": { "post": { "tags": [ "public-api" ], "summary": "Commit Opportunity Public", "description": "Decide on one suggestion: commit it, dismiss it, or snooze it.\n\nCommitting freezes its measurement plan (hard rule 7), which is what makes\na measured result possible later. No verb here grants autonomy: the API\ncannot raise a rung, by construction.\n\nEditor authority: every verb here writes, and a commit creates tracked work\nfor the whole team. Read access (team grants, client assignments) must not\nreach it.", "operationId": "commit_opportunity_public_commit_opportunity_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitOpportunityRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitOpportunityPublicResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-results": { "get": { "tags": [ "public-api" ], "summary": "Get Results Public", "description": "What completed work changed, measured before and after.\n\nResults are never self-reported and never claim causation.", "operationId": "get_results_public_get_results_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "earned|no_change|harm|couldnt_measure", "title": "Verdict" }, "description": "earned|no_change|harm|couldnt_measure" }, { "name": "family", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family" } }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 3650, "minimum": 1 }, { "type": "null" } ], "description": "Only results measured in the last N days", "title": "Days" }, "description": "Only results measured in the last N days" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-proof": { "get": { "tags": [ "public-api" ], "summary": "Get Proof Public", "description": "Deprecated compatibility alias for `/get-results`.", "operationId": "get_proof_public_get_proof_get", "deprecated": true, "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "verdict", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "earned|no_change|harm|couldnt_measure", "title": "Verdict" }, "description": "earned|no_change|harm|couldnt_measure" }, { "name": "family", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family" } }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 3650, "minimum": 1 }, { "type": "null" } ], "description": "Only results measured in the last N days", "title": "Days" }, "description": "Only results measured in the last N days" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/get-pages": { "get": { "tags": [ "public-api" ], "summary": "Get Pages Public", "description": "The page registry: one row per URL this brand appears on or owns.", "operationId": "get_pages_public_get_pages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "brand_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Brand UUID", "title": "Brand Id" }, "description": "Brand UUID" }, { "name": "ownership", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "owned|competitor|editorial|social|video|other", "title": "Ownership" }, "description": "owned|competitor|editorial|social|video|other" }, { "name": "tracked", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Tracked" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagesResponse" } } } }, "401": { "description": "Missing, malformed, or expired credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "402": { "description": "The current plan does not fund this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "403": { "description": "Invalid credentials, missing brand access, or insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "500": { "description": "The operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "503": { "description": "Authentication, entitlement, or a required dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ActionPublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "first_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Step" }, "category": { "type": "string", "title": "Category" }, "action_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Type" }, "effort": { "type": "string", "title": "Effort" }, "impact": { "type": "string", "title": "Impact" }, "priority_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Priority Score" }, "priority_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Priority Level" }, "status": { "type": "string", "title": "Status" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "time_horizon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Horizon" }, "affected_models": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Affected Models" }, "affected_query_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Affected Query Count" }, "deep_link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deep Link" }, "pinned": { "type": "boolean", "title": "Pinned", "default": false }, "snoozed_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snoozed Until" }, "action_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Action Data" }, "execution": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Execution" }, "family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Family" }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Id" }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Url" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result" }, "proof": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Proof" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "id", "title", "category", "effort", "impact", "status", "created_at", "updated_at" ], "title": "ActionPublicItem", "description": "Single brand_actions row, shaped for external consumers." }, "ActionStatsPublicResponse": { "properties": { "total_pending": { "type": "integer", "title": "Total Pending" }, "total_in_progress": { "type": "integer", "title": "Total In Progress" }, "total_completed": { "type": "integer", "title": "Total Completed" }, "total_dismissed": { "type": "integer", "title": "Total Dismissed" }, "total_snoozed": { "type": "integer", "title": "Total Snoozed" }, "quick_wins": { "type": "integer", "title": "Quick Wins" }, "completion_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Completion Rate" }, "completed_this_week": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed This Week" }, "by_type": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "By Type" }, "by_category": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "By Category" }, "by_source": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "By Source" } }, "type": "object", "required": [ "total_pending", "total_in_progress", "total_completed", "total_dismissed", "total_snoozed", "quick_wins" ], "title": "ActionStatsPublicResponse", "description": "GET /get-action-stats response." }, "ActionsPublicResponse": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/ActionPublicItem" }, "type": "array", "title": "Actions" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } }, "type": "object", "required": [ "actions", "pagination" ], "title": "ActionsPublicResponse", "description": "GET /get-actions response." }, "AddMarketRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "location": { "type": "string", "title": "Location" }, "market_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Market Name" } }, "type": "object", "required": [ "brand_id", "location" ], "title": "AddMarketRequest", "description": "POST /get-brands/markets request body." }, "AuditFindingsResponse": { "properties": { "status": { "type": "string", "enum": [ "ok", "no_audit_yet" ], "title": "Status", "default": "ok" }, "audit_summary": { "anyOf": [ { "$ref": "#/components/schemas/AuditFindingsSummary" }, { "type": "null" } ] }, "issues": { "items": { "$ref": "#/components/schemas/AuditIssueItem" }, "type": "array", "title": "Issues", "default": [] }, "issues_count": { "type": "integer", "title": "Issues Count", "default": 0 }, "pages": { "items": { "$ref": "#/components/schemas/AuditPageItem" }, "type": "array", "title": "Pages", "default": [] }, "pages_count": { "type": "integer", "title": "Pages Count", "default": 0 }, "filters_applied": { "additionalProperties": true, "type": "object", "title": "Filters Applied" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "title": "AuditFindingsResponse", "description": "GET /get-audit-findings response." }, "AuditFindingsSummary": { "properties": { "audit_id": { "type": "string", "title": "Audit Id" }, "overall_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Overall Score" }, "pages_crawled": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pages Crawled" }, "critical_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Critical Issues" }, "high_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "High Issues" }, "medium_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Medium Issues" }, "low_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Low Issues" }, "detected_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detected Platform" }, "site_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Url" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "has_llms_txt": { "type": "boolean", "title": "Has Llms Txt", "default": false }, "ai_crawler_blocked": { "type": "boolean", "title": "Ai Crawler Blocked", "default": false }, "has_sitemap": { "type": "boolean", "title": "Has Sitemap", "default": false } }, "type": "object", "required": [ "audit_id" ], "title": "AuditFindingsSummary", "description": "Audit-level rollup attached to /get-audit-findings." }, "AuditIssueItem": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "check_name": { "type": "string", "title": "Check Name" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "impact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Impact" }, "affected_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Affected Count" }, "affected_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Affected Percent" }, "sample_urls": { "items": { "type": "string" }, "type": "array", "title": "Sample Urls", "default": [] }, "fix_effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fix Effort" }, "fix_impact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fix Impact" }, "implementation": { "items": {}, "type": "array", "title": "Implementation", "default": [] }, "fixed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fixed At" } }, "type": "object", "required": [ "check_name" ], "title": "AuditIssueItem", "description": "One audit_issues row, shaped for external consumers." }, "AuditPageItem": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "url": { "type": "string", "title": "Url" }, "final_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Final Url" }, "page_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Type" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "technical_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Technical Score" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "word_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Word Count" }, "failed_checks": { "items": { "type": "string" }, "type": "array", "title": "Failed Checks", "default": [] }, "warning_checks": { "items": { "type": "string" }, "type": "array", "title": "Warning Checks", "default": [] }, "is_deep_analyzed": { "type": "boolean", "title": "Is Deep Analyzed", "default": false } }, "type": "object", "required": [ "url" ], "title": "AuditPageItem", "description": "One audit_pages row, shaped for external consumers." }, "AuditSummaryItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "site_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Url" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "overall_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Overall Score" }, "pages_crawled": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pages Crawled" }, "critical_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Critical Issues" }, "high_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "High Issues" }, "medium_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Medium Issues" }, "low_issues": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Low Issues" }, "detected_platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detected Platform" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" } }, "type": "object", "required": [ "id", "brand_id" ], "title": "AuditSummaryItem", "description": "One audit row from the listing." }, "AuditsListResponse": { "properties": { "audits": { "items": { "$ref": "#/components/schemas/AuditSummaryItem" }, "type": "array", "title": "Audits" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "audits", "total" ], "title": "AuditsListResponse", "description": "GET /get-audits response." }, "Body_trigger_public_crawler_verification_ping_api_v1_crawler_verification_ping_post": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" } }, "type": "object", "required": [ "brand_id" ], "title": "Body_trigger_public_crawler_verification_ping_api_v1_crawler_verification_ping_post" }, "Body_trigger_public_crawler_verification_ping_crawler_verification_ping_post": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" } }, "type": "object", "required": [ "brand_id" ], "title": "Body_trigger_public_crawler_verification_ping_crawler_verification_ping_post" }, "Body_trigger_public_crawler_verification_ping_mcp_crawler_verification_ping_post": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" } }, "type": "object", "required": [ "brand_id" ], "title": "Body_trigger_public_crawler_verification_ping_mcp_crawler_verification_ping_post" }, "BrandAliasesResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "brand_id": { "type": "string", "title": "Brand Id" }, "aliases": { "items": { "type": "string" }, "type": "array", "title": "Aliases" }, "reports_updated": { "type": "integer", "title": "Reports Updated" } }, "type": "object", "required": [ "success", "brand_id", "aliases", "reports_updated" ], "title": "BrandAliasesResponse" }, "BrandGroupsPublicResponse": { "properties": { "groups": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Groups" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "groups", "total" ], "title": "BrandGroupsPublicResponse" }, "BrandItemExtended": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "favicon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Favicon" }, "active": { "type": "boolean", "title": "Active", "default": true }, "role": { "type": "string", "enum": [ "owner", "editor", "viewer" ], "title": "Role", "default": "owner" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "location_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Region" }, "location_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location City" }, "markets": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MarketItem" }, "type": "array" }, { "type": "null" } ], "title": "Markets" }, "aliases": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Aliases" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "id", "name" ], "title": "BrandItemExtended", "description": "Extended brand with optional markets and aliases." }, "BrandPerformance": { "properties": { "brand_name": { "type": "string", "title": "Brand Name" }, "total_mentions": { "type": "integer", "title": "Total Mentions" }, "avg_rank": { "type": "number", "title": "Avg Rank" } }, "type": "object", "required": [ "brand_name", "total_mentions", "avg_rank" ], "title": "BrandPerformance", "description": "Brand performance summary." }, "BrandsExtendedResponse": { "properties": { "brands": { "items": { "$ref": "#/components/schemas/BrandItemExtended" }, "type": "array", "title": "Brands" } }, "type": "object", "required": [ "brands" ], "title": "BrandsExtendedResponse", "description": "GET /get-brands response (extended)." }, "BulkActivateRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "prompt_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Prompt Ids" } }, "type": "object", "required": [ "brand_id", "prompt_ids" ], "title": "BulkActivateRequest" }, "BulkActivateResponse": { "properties": { "updated": { "type": "integer", "title": "Updated" }, "prompt_ids": { "items": { "type": "string" }, "type": "array", "title": "Prompt Ids" } }, "type": "object", "required": [ "updated", "prompt_ids" ], "title": "BulkActivateResponse" }, "BulkCreatePromptItem": { "properties": { "text": { "type": "string", "title": "Text" }, "active": { "type": "boolean", "title": "Active", "default": true }, "focus_area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus Area" }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience" } }, "type": "object", "required": [ "text" ], "title": "BulkCreatePromptItem" }, "BulkCreatePromptsRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "prompts": { "items": { "$ref": "#/components/schemas/BulkCreatePromptItem" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Prompts" } }, "type": "object", "required": [ "brand_id", "prompts" ], "title": "BulkCreatePromptsRequest" }, "BulkCreatePromptsResponse": { "properties": { "created": { "type": "integer", "title": "Created" }, "failed": { "type": "integer", "title": "Failed" }, "results": { "items": { "$ref": "#/components/schemas/BulkPromptResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "created", "failed", "results" ], "title": "BulkCreatePromptsResponse" }, "BulkDeletePromptsRequest": { "properties": { "prompt_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Prompt Ids" } }, "type": "object", "required": [ "prompt_ids" ], "title": "BulkDeletePromptsRequest" }, "BulkDeletePromptsResponse": { "properties": { "deleted": { "type": "integer", "title": "Deleted" }, "failed": { "type": "integer", "title": "Failed" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "deleted", "failed", "results" ], "title": "BulkDeletePromptsResponse" }, "BulkPromptResult": { "properties": { "index": { "type": "integer", "title": "Index" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "text": { "type": "string", "title": "Text" }, "success": { "type": "boolean", "title": "Success" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "index", "text", "success" ], "title": "BulkPromptResult" }, "CitationAppearance": { "properties": { "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" } }, "type": "object", "title": "CitationAppearance" }, "CitationDetailResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "url": { "type": "string", "title": "Url" }, "domain": { "type": "string", "title": "Domain" }, "h1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "H1" }, "sentiment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sentiment" }, "sentiment_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment Label" }, "mentions_brand": { "type": "boolean", "title": "Mentions Brand", "default": false }, "competitors": { "items": { "type": "string" }, "type": "array", "title": "Competitors", "default": [] }, "topics": { "items": { "type": "string" }, "type": "array", "title": "Topics", "default": [] }, "appearance_count": { "type": "integer", "title": "Appearance Count", "default": 1 }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "prompts": { "items": { "type": "string" }, "type": "array", "title": "Prompts", "default": [] }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "appearances": { "items": { "$ref": "#/components/schemas/CitationAppearance" }, "type": "array", "title": "Appearances", "default": [] }, "related_citations": { "items": { "type": "string" }, "type": "array", "title": "Related Citations", "default": [] } }, "type": "object", "required": [ "brand", "url", "domain" ], "title": "CitationDetailResponse", "description": "GET /get-citations?view=detail" }, "CitationItem": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "domain": { "type": "string", "title": "Domain" }, "page_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Title" }, "prompt": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Prompt", "default": {} }, "prompts": { "items": { "type": "string" }, "type": "array", "title": "Prompts", "default": [] }, "metrics": { "additionalProperties": true, "type": "object", "title": "Metrics", "default": {} }, "seo": { "additionalProperties": true, "type": "object", "title": "Seo", "default": {} }, "source_type": { "type": "string", "title": "Source Type", "default": "organic" }, "search_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search Model" }, "ai_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Provider" }, "ai_providers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ai Providers" }, "provider_counts": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Provider Counts" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date" }, "mentions_brand": { "type": "boolean", "title": "Mentions Brand", "default": false }, "competitors": { "items": { "type": "string" }, "type": "array", "title": "Competitors", "default": [] }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "required": [ "id", "url", "domain" ], "title": "CitationItem", "description": "Citation in the API response." }, "CitationsAnalyticsResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "summary": { "$ref": "#/components/schemas/CitationsSummary" }, "top_domains": { "items": { "$ref": "#/components/schemas/CitationsTopDomain" }, "type": "array", "title": "Top Domains" }, "top_competitors": { "items": { "$ref": "#/components/schemas/CitationsTopCompetitor" }, "type": "array", "title": "Top Competitors" } }, "type": "object", "required": [ "brand", "summary", "top_domains", "top_competitors" ], "title": "CitationsAnalyticsResponse", "description": "GET /get-citations?view=analytics" }, "CitationsByModelItem": { "properties": { "model": { "type": "string", "title": "Model" }, "total_citations": { "type": "integer", "title": "Total Citations" }, "brand_mentions": { "type": "integer", "title": "Brand Mentions" }, "unique_sources": { "type": "integer", "title": "Unique Sources" }, "top_domains": { "items": { "type": "string" }, "type": "array", "title": "Top Domains", "default": [] } }, "type": "object", "required": [ "model", "total_citations", "brand_mentions", "unique_sources" ], "title": "CitationsByModelItem" }, "CitationsByModelResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "models": { "items": { "$ref": "#/components/schemas/CitationsByModelItem" }, "type": "array", "title": "Models" } }, "type": "object", "required": [ "brand", "models" ], "title": "CitationsByModelResponse", "description": "GET /get-citations?view=by_model" }, "CitationsCompetitorPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "mentions": { "type": "integer", "title": "Mentions" } }, "type": "object", "required": [ "date", "mentions" ], "title": "CitationsCompetitorPoint" }, "CitationsDomainPage": { "properties": { "url": { "type": "string", "title": "Url" }, "h1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "H1" }, "sentiment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sentiment" }, "mentions_brand": { "type": "boolean", "title": "Mentions Brand", "default": false }, "competitors": { "items": { "type": "string" }, "type": "array", "title": "Competitors", "default": [] }, "appearance_count": { "type": "integer", "title": "Appearance Count", "default": 1 } }, "type": "object", "required": [ "url" ], "title": "CitationsDomainPage" }, "CitationsFeedEvent": { "properties": { "event_type": { "type": "string", "title": "Event Type" }, "url": { "type": "string", "title": "Url" }, "domain": { "type": "string", "title": "Domain" }, "h1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "H1" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" }, "timestamp": { "type": "string", "title": "Timestamp" }, "mentions_brand": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Mentions Brand" }, "sentiment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sentiment" }, "prev_sentiment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Prev Sentiment" }, "appearance_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Appearance Count" }, "prev_appearance_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Prev Appearance Count" }, "new_competitors": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "New Competitors" }, "prompts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Prompts" } }, "type": "object", "required": [ "event_type", "url", "domain", "timestamp" ], "title": "CitationsFeedEvent" }, "CitationsFeedResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "events": { "items": { "$ref": "#/components/schemas/CitationsFeedEvent" }, "type": "array", "title": "Events" }, "current_snapshot_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Snapshot Date" }, "previous_snapshot_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Snapshot Date" }, "total_current": { "type": "integer", "title": "Total Current", "default": 0 }, "total_previous": { "type": "integer", "title": "Total Previous", "default": 0 } }, "type": "object", "required": [ "brand", "events" ], "title": "CitationsFeedResponse", "description": "GET /get-citations?view=feed" }, "CitationsHeatmapCell": { "properties": { "domain": { "type": "string", "title": "Domain" }, "brand": { "type": "string", "title": "Brand" }, "is_present": { "type": "boolean", "title": "Is Present" }, "mention_count": { "type": "integer", "title": "Mention Count" } }, "type": "object", "required": [ "domain", "brand", "is_present", "mention_count" ], "title": "CitationsHeatmapCell" }, "CitationsHeatmapResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "domains": { "items": { "type": "string" }, "type": "array", "title": "Domains" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" }, "your_brand": { "type": "string", "title": "Your Brand" }, "cells": { "items": { "$ref": "#/components/schemas/CitationsHeatmapCell" }, "type": "array", "title": "Cells" }, "your_coverage": { "type": "number", "title": "Your Coverage" }, "competitor_coverage": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Competitor Coverage" } }, "type": "object", "required": [ "brand", "domains", "brands", "your_brand", "cells", "your_coverage", "competitor_coverage" ], "title": "CitationsHeatmapResponse", "description": "GET /get-citations?view=heatmap" }, "CitationsHistoryResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "brand_time_series": { "items": { "$ref": "#/components/schemas/CitationsTimeSeriesPoint" }, "type": "array", "title": "Brand Time Series" }, "competitor_time_series": { "additionalProperties": { "items": { "$ref": "#/components/schemas/CitationsCompetitorPoint" }, "type": "array" }, "type": "object", "title": "Competitor Time Series" }, "snapshots_available": { "type": "integer", "title": "Snapshots Available" }, "date_range": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Date Range" } }, "type": "object", "required": [ "brand", "brand_time_series", "competitor_time_series", "snapshots_available", "date_range" ], "title": "CitationsHistoryResponse", "description": "GET /get-citations?view=history" }, "CitationsQueriesResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "clusters": { "items": { "$ref": "#/components/schemas/CitationsQueryCluster" }, "type": "array", "title": "Clusters" }, "top_queries": { "items": { "$ref": "#/components/schemas/CitationsQueryInsight" }, "type": "array", "title": "Top Queries" }, "gap_queries": { "items": { "$ref": "#/components/schemas/CitationsQueryInsight" }, "type": "array", "title": "Gap Queries" }, "coverage_by_intent": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Coverage By Intent" }, "new_queries_count": { "type": "integer", "title": "New Queries Count" }, "rising_queries_count": { "type": "integer", "title": "Rising Queries Count" } }, "type": "object", "required": [ "brand", "clusters", "top_queries", "gap_queries", "coverage_by_intent", "new_queries_count", "rising_queries_count" ], "title": "CitationsQueriesResponse", "description": "GET /get-citations?view=queries" }, "CitationsQueryCluster": { "properties": { "intent": { "type": "string", "title": "Intent" }, "label": { "type": "string", "title": "Label" }, "queries": { "items": { "type": "string" }, "type": "array", "title": "Queries" }, "total_citations": { "type": "integer", "title": "Total Citations" }, "brand_appears_in": { "type": "integer", "title": "Brand Appears In" }, "coverage_rate": { "type": "number", "title": "Coverage Rate" } }, "type": "object", "required": [ "intent", "label", "queries", "total_citations", "brand_appears_in", "coverage_rate" ], "title": "CitationsQueryCluster" }, "CitationsQueryInsight": { "properties": { "query": { "type": "string", "title": "Query" }, "intent": { "type": "string", "title": "Intent" }, "frequency": { "type": "integer", "title": "Frequency" }, "citations_found": { "type": "integer", "title": "Citations Found" }, "brand_appears": { "type": "boolean", "title": "Brand Appears" }, "top_sources": { "items": { "type": "string" }, "type": "array", "title": "Top Sources" }, "competitors_appearing": { "items": { "type": "string" }, "type": "array", "title": "Competitors Appearing" }, "is_new": { "type": "boolean", "title": "Is New" }, "trend": { "type": "string", "title": "Trend" } }, "type": "object", "required": [ "query", "intent", "frequency", "citations_found", "brand_appears", "top_sources", "competitors_appearing", "is_new", "trend" ], "title": "CitationsQueryInsight" }, "CitationsResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "citations": { "items": { "$ref": "#/components/schemas/CitationItem" }, "type": "array", "title": "Citations" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } }, "type": "object", "required": [ "brand", "citations", "pagination" ], "title": "CitationsResponse", "description": "GET /get-citations response." }, "CitationsSourceResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "domain": { "type": "string", "title": "Domain" }, "total_citations": { "type": "integer", "title": "Total Citations" }, "unique_pages": { "type": "integer", "title": "Unique Pages" }, "mentions_you": { "type": "boolean", "title": "Mentions You" }, "mention_count": { "type": "integer", "title": "Mention Count" }, "competitors_on_domain": { "items": { "type": "string" }, "type": "array", "title": "Competitors On Domain" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sentiment" }, "pages": { "items": { "$ref": "#/components/schemas/CitationsDomainPage" }, "type": "array", "title": "Pages" }, "first_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "required": [ "brand", "domain", "total_citations", "unique_pages", "mentions_you", "mention_count", "competitors_on_domain", "pages" ], "title": "CitationsSourceResponse", "description": "GET /get-citations?view=sources" }, "CitationsSummary": { "properties": { "total_citations": { "type": "integer", "title": "Total Citations" }, "unique_sources": { "type": "integer", "title": "Unique Sources" }, "total_domains": { "type": "integer", "title": "Total Domains" }, "brand_mentions": { "type": "integer", "title": "Brand Mentions" }, "competitor_mentions": { "type": "integer", "title": "Competitor Mentions" }, "positive_percentage": { "type": "number", "title": "Positive Percentage" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sentiment" }, "citations_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Citations Change" }, "brand_mentions_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Brand Mentions Change" }, "source_type_breakdown": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SourceTypeStats" }, "type": "array" }, { "type": "null" } ], "title": "Source Type Breakdown" } }, "type": "object", "required": [ "total_citations", "unique_sources", "total_domains", "brand_mentions", "competitor_mentions", "positive_percentage" ], "title": "CitationsSummary" }, "CitationsTimeSeriesPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "total_citations": { "type": "integer", "title": "Total Citations" }, "brand_mentions": { "type": "integer", "title": "Brand Mentions" }, "unique_sources": { "type": "integer", "title": "Unique Sources" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sentiment" } }, "type": "object", "required": [ "date", "total_citations", "brand_mentions", "unique_sources" ], "title": "CitationsTimeSeriesPoint" }, "CitationsTopCompetitor": { "properties": { "name": { "type": "string", "title": "Name" }, "times_cited": { "type": "integer", "title": "Times Cited" }, "unique_sources": { "type": "integer", "title": "Unique Sources" }, "citation_share": { "type": "number", "title": "Citation Share" } }, "type": "object", "required": [ "name", "times_cited", "unique_sources", "citation_share" ], "title": "CitationsTopCompetitor" }, "CitationsTopDomain": { "properties": { "domain": { "type": "string", "title": "Domain" }, "times_cited": { "type": "integer", "title": "Times Cited" }, "unique_pages": { "type": "integer", "title": "Unique Pages" }, "citation_share": { "type": "number", "title": "Citation Share" }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" } }, "type": "object", "required": [ "domain", "times_cited", "unique_pages", "citation_share" ], "title": "CitationsTopDomain" }, "CitationsTopPage": { "properties": { "url": { "type": "string", "title": "Url" }, "domain": { "type": "string", "title": "Domain" }, "h1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "H1" }, "appearance_count": { "type": "integer", "title": "Appearance Count", "default": 1 }, "sentiment": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sentiment" }, "mentions_brand": { "type": "boolean", "title": "Mentions Brand", "default": false }, "competitors": { "items": { "type": "string" }, "type": "array", "title": "Competitors", "default": [] }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Type" } }, "type": "object", "required": [ "url", "domain" ], "title": "CitationsTopPage" }, "CitationsTopPagesResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "pages": { "items": { "$ref": "#/components/schemas/CitationsTopPage" }, "type": "array", "title": "Pages" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "brand", "pages", "total" ], "title": "CitationsTopPagesResponse", "description": "GET /get-citations?view=top_pages" }, "CoOccurrence": { "properties": { "competitor": { "type": "string", "title": "Competitor" }, "count": { "type": "integer", "title": "Count" }, "primary_wins_pct": { "type": "number", "title": "Primary Wins Pct" } }, "type": "object", "required": [ "competitor", "count", "primary_wins_pct" ], "title": "CoOccurrence", "description": "Brand co-occurrence data." }, "CommitOpportunityPublicResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "opportunity_id": { "type": "string", "title": "Opportunity Id" }, "action_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Id" }, "measurement_plan": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Measurement Plan" } }, "additionalProperties": true, "type": "object", "required": [ "status", "opportunity_id" ], "title": "CommitOpportunityPublicResponse" }, "CommitOpportunityRequest": { "properties": { "opportunity_id": { "type": "string", "title": "Opportunity Id" }, "action": { "type": "string", "title": "Action", "default": "commit" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "snooze_days": { "anyOf": [ { "type": "integer", "maximum": 90.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Snooze Days" } }, "type": "object", "required": [ "opportunity_id" ], "title": "CommitOpportunityRequest" }, "CompareBrandsPublicResponse": { "properties": { "brands": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Brands" }, "period_days": { "type": "integer", "title": "Period Days" }, "metrics": { "additionalProperties": true, "type": "object", "title": "Metrics" } }, "type": "object", "required": [ "brands", "period_days", "metrics" ], "title": "CompareBrandsPublicResponse" }, "CompareBrandsRequest": { "properties": { "brand_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 10, "minItems": 2, "title": "Brand Ids" }, "days": { "type": "integer", "maximum": 365.0, "minimum": 7.0, "title": "Days", "default": 30 }, "metrics": { "anyOf": [ { "items": { "type": "string", "enum": [ "visibility", "citations", "actions" ] }, "type": "array" }, { "type": "null" } ], "title": "Metrics" } }, "type": "object", "required": [ "brand_ids" ], "title": "CompareBrandsRequest", "description": "POST /agency/compare-brands body." }, "CompetitorAlertItem": { "properties": { "type": { "type": "string", "title": "Type" }, "severity": { "type": "string", "title": "Severity" }, "message": { "type": "string", "title": "Message" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "competitor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Competitor" } }, "type": "object", "required": [ "type", "severity", "message" ], "title": "CompetitorAlertItem" }, "CompetitorArenaPrompt": { "properties": { "prompt_text": { "type": "string", "title": "Prompt Text" }, "your_rank": { "type": "integer", "title": "Your Rank" }, "your_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Your Score" }, "leader": { "type": "string", "title": "Leader" }, "leader_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Leader Score" }, "gap_to_leader": { "type": "number", "title": "Gap To Leader" }, "total_competitors": { "type": "integer", "title": "Total Competitors" }, "rankings": { "items": { "$ref": "#/components/schemas/CompetitorArenaRanking" }, "type": "array", "title": "Rankings" } }, "type": "object", "required": [ "prompt_text", "your_rank", "leader", "gap_to_leader", "total_competitors", "rankings" ], "title": "CompetitorArenaPrompt" }, "CompetitorArenaRanking": { "properties": { "rank": { "type": "integer", "title": "Rank" }, "name": { "type": "string", "title": "Name" }, "score": { "type": "number", "title": "Score" }, "is_you": { "type": "boolean", "title": "Is You", "default": false } }, "type": "object", "required": [ "rank", "name", "score" ], "title": "CompetitorArenaRanking" }, "CompetitorArenaResponse": { "properties": { "prompts": { "items": { "$ref": "#/components/schemas/CompetitorArenaPrompt" }, "type": "array", "title": "Prompts" }, "total_prompts": { "type": "integer", "title": "Total Prompts" }, "prompts_you_lead": { "type": "integer", "title": "Prompts You Lead" }, "prompts_top_3": { "type": "integer", "title": "Prompts Top 3" } }, "type": "object", "required": [ "prompts", "total_prompts", "prompts_you_lead", "prompts_top_3" ], "title": "CompetitorArenaResponse", "description": "GET /get-competitor-data?view=arena" }, "CompetitorBrandStats": { "properties": { "name": { "type": "string", "title": "Name" }, "visibility": { "type": "number", "title": "Visibility" }, "visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Change" }, "avg_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Rank" }, "rank1_count": { "type": "integer", "title": "Rank1 Count", "default": 0 } }, "type": "object", "required": [ "name", "visibility" ], "title": "CompetitorBrandStats" }, "CompetitorByModelResponse": { "properties": { "llms": { "items": { "type": "string" }, "type": "array", "title": "Llms" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" }, "your_brand": { "type": "string", "title": "Your Brand" }, "heatmap": { "items": { "$ref": "#/components/schemas/CompetitorLLMCell" }, "type": "array", "title": "Heatmap" }, "insights": { "items": { "$ref": "#/components/schemas/CompetitorLLMInsight" }, "type": "array", "title": "Insights" }, "your_best_llm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Your Best Llm" }, "your_worst_llm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Your Worst Llm" } }, "type": "object", "required": [ "llms", "brands", "your_brand", "heatmap", "insights" ], "title": "CompetitorByModelResponse", "description": "GET /get-competitor-data?view=by-model" }, "CompetitorDataResponse": { "properties": { "brand_performance_summary": { "items": { "$ref": "#/components/schemas/BrandPerformance" }, "type": "array", "title": "Brand Performance Summary" }, "top_spot_ownership": { "items": { "$ref": "#/components/schemas/TopSpotOwnership" }, "type": "array", "title": "Top Spot Ownership" }, "primary_brand_cooccurrences": { "items": { "$ref": "#/components/schemas/CoOccurrence" }, "type": "array", "title": "Primary Brand Cooccurrences" } }, "type": "object", "required": [ "brand_performance_summary", "top_spot_ownership", "primary_brand_cooccurrences" ], "title": "CompetitorDataResponse", "description": "GET /get-competitor-data response." }, "CompetitorH2HRecord": { "properties": { "your_wins": { "type": "integer", "title": "Your Wins" }, "rival_wins": { "type": "integer", "title": "Rival Wins" }, "ties": { "type": "integer", "title": "Ties" }, "your_win_rate": { "type": "number", "title": "Your Win Rate" }, "total_matchups": { "type": "integer", "title": "Total Matchups" } }, "type": "object", "required": [ "your_wins", "rival_wins", "ties", "your_win_rate", "total_matchups" ], "title": "CompetitorH2HRecord" }, "CompetitorH2HResponse": { "properties": { "you": { "$ref": "#/components/schemas/CompetitorBrandStats" }, "rival": { "$ref": "#/components/schemas/CompetitorBrandStats" }, "head_to_head": { "$ref": "#/components/schemas/CompetitorH2HRecord" }, "where_rival_wins": { "items": { "$ref": "#/components/schemas/CompetitorPromptMatchup" }, "type": "array", "title": "Where Rival Wins" }, "where_you_win": { "items": { "$ref": "#/components/schemas/CompetitorPromptMatchup" }, "type": "array", "title": "Where You Win" }, "available_rivals": { "items": { "type": "string" }, "type": "array", "title": "Available Rivals" } }, "type": "object", "required": [ "you", "rival", "head_to_head", "where_rival_wins", "where_you_win", "available_rivals" ], "title": "CompetitorH2HResponse", "description": "GET /get-competitor-data?view=head-to-head" }, "CompetitorHeatmapCell": { "properties": { "brand": { "type": "string", "title": "Brand" }, "model": { "type": "string", "title": "Model" }, "visibility": { "type": "number", "title": "Visibility" }, "avg_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Rank" }, "mentions": { "type": "integer", "title": "Mentions", "default": 0 }, "is_you": { "type": "boolean", "title": "Is You", "default": false } }, "type": "object", "required": [ "brand", "model", "visibility" ], "title": "CompetitorHeatmapCell" }, "CompetitorHeatmapResponse": { "properties": { "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" }, "models": { "items": { "type": "string" }, "type": "array", "title": "Models" }, "your_brand": { "type": "string", "title": "Your Brand" }, "cells": { "items": { "$ref": "#/components/schemas/CompetitorHeatmapCell" }, "type": "array", "title": "Cells" }, "your_best_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Your Best Model" }, "your_worst_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Your Worst Model" } }, "type": "object", "required": [ "brands", "models", "your_brand", "cells" ], "title": "CompetitorHeatmapResponse", "description": "GET /get-competitor-data?view=heatmap" }, "CompetitorLLMCell": { "properties": { "brand": { "type": "string", "title": "Brand" }, "llm": { "type": "string", "title": "Llm" }, "visibility": { "type": "number", "title": "Visibility" }, "avg_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Rank" }, "mentions": { "type": "integer", "title": "Mentions" }, "is_you": { "type": "boolean", "title": "Is You", "default": false } }, "type": "object", "required": [ "brand", "llm", "visibility", "mentions" ], "title": "CompetitorLLMCell" }, "CompetitorLLMInsight": { "properties": { "type": { "type": "string", "title": "Type" }, "llm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Llm" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "type", "message" ], "title": "CompetitorLLMInsight" }, "CompetitorManageResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" }, "competitor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Competitor" }, "tracked": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tracked" }, "hidden": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Hidden" }, "already_tracked": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Already Tracked" }, "already_hidden": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Already Hidden" } }, "additionalProperties": true, "type": "object", "required": [ "brand_id" ], "title": "CompetitorManageResponse" }, "CompetitorOpportunityItem": { "properties": { "prompt_text": { "type": "string", "title": "Prompt Text" }, "your_rank": { "type": "integer", "title": "Your Rank" }, "gap_to_next": { "type": "number", "title": "Gap To Next" }, "next_competitor": { "type": "string", "title": "Next Competitor" }, "opportunity_score": { "type": "number", "title": "Opportunity Score" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "required": [ "prompt_text", "your_rank", "gap_to_next", "next_competitor", "opportunity_score" ], "title": "CompetitorOpportunityItem" }, "CompetitorOverTimeBrand": { "properties": { "name": { "type": "string", "title": "Name" }, "is_you": { "type": "boolean", "title": "Is You", "default": false }, "data_points": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data Points" } }, "type": "object", "required": [ "name", "data_points" ], "title": "CompetitorOverTimeBrand" }, "CompetitorOverTimeResponse": { "properties": { "brands": { "items": { "$ref": "#/components/schemas/CompetitorOverTimeBrand" }, "type": "array", "title": "Brands" }, "period_days": { "type": "integer", "title": "Period Days" }, "date_range": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Date Range" } }, "type": "object", "required": [ "brands", "period_days", "date_range" ], "title": "CompetitorOverTimeResponse", "description": "GET /get-competitor-data?view=over_time" }, "CompetitorPosition": { "properties": { "name": { "type": "string", "title": "Name" }, "position": { "type": "integer", "title": "Position" } }, "type": "object", "required": [ "name", "position" ], "title": "CompetitorPosition", "description": "Competitor position in an opportunity." }, "CompetitorPromptMatchup": { "properties": { "prompt_text": { "type": "string", "title": "Prompt Text" }, "your_rank": { "type": "integer", "title": "Your Rank" }, "rival_rank": { "type": "integer", "title": "Rival Rank" } }, "type": "object", "required": [ "prompt_text", "your_rank", "rival_rank" ], "title": "CompetitorPromptMatchup" }, "CompetitorThreatItem": { "properties": { "competitor": { "type": "string", "title": "Competitor" }, "severity": { "type": "string", "title": "Severity" }, "pressure_score": { "type": "number", "title": "Pressure Score" }, "win_rate_against_you": { "type": "number", "title": "Win Rate Against You" }, "cooccurrence_count": { "type": "integer", "title": "Cooccurrence Count" }, "trend": { "type": "string", "title": "Trend" }, "description": { "type": "string", "title": "Description" } }, "type": "object", "required": [ "competitor", "severity", "pressure_score", "win_rate_against_you", "cooccurrence_count", "trend", "description" ], "title": "CompetitorThreatItem" }, "CompetitorThreatsResponse": { "properties": { "threats": { "items": { "$ref": "#/components/schemas/CompetitorThreatItem" }, "type": "array", "title": "Threats" }, "opportunities": { "items": { "$ref": "#/components/schemas/CompetitorOpportunityItem" }, "type": "array", "title": "Opportunities" }, "alerts": { "items": { "$ref": "#/components/schemas/CompetitorAlertItem" }, "type": "array", "title": "Alerts" }, "summary": { "additionalProperties": true, "type": "object", "title": "Summary" } }, "type": "object", "required": [ "threats", "opportunities", "alerts", "summary" ], "title": "CompetitorThreatsResponse", "description": "GET /get-competitor-data?view=threats" }, "ContentArticlesPublicResponse": { "properties": { "articles": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Articles" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "articles", "total", "limit", "offset" ], "title": "ContentArticlesPublicResponse" }, "ContentIdeaPublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type" }, "query": { "type": "string", "title": "Query" }, "insight": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Insight" }, "opportunity_score": { "type": "integer", "title": "Opportunity Score", "default": 0 }, "status": { "type": "string", "title": "Status", "default": "active" }, "recommended_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recommended Template" }, "competitors_appearing": { "items": { "type": "string" }, "type": "array", "title": "Competitors Appearing", "default": [] }, "ai_models": { "items": { "type": "string" }, "type": "array", "title": "Ai Models", "default": [] }, "your_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Your Position" }, "created_at": { "type": "string", "title": "Created At" }, "potential": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Potential" }, "angle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Angle" }, "why_now": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Why Now" }, "sub_questions": { "items": { "type": "string" }, "type": "array", "title": "Sub Questions", "default": [] }, "proof_points": { "items": { "type": "string" }, "type": "array", "title": "Proof Points", "default": [] }, "competitors_winning": { "items": { "type": "string" }, "type": "array", "title": "Competitors Winning", "default": [] }, "is_quick_win": { "type": "boolean", "title": "Is Quick Win", "default": false } }, "type": "object", "required": [ "id", "type", "query", "created_at" ], "title": "ContentIdeaPublicItem", "description": "Public API representation of a content idea." }, "ContentIdeasMeta": { "properties": { "generated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generated At" }, "generation_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generation Status" }, "total_opportunities": { "type": "integer", "title": "Total Opportunities", "default": 0 } }, "type": "object", "title": "ContentIdeasMeta", "description": "Metadata about content ideas generation." }, "ContentIdeasPublicResponse": { "properties": { "ideas": { "items": { "$ref": "#/components/schemas/ContentIdeaPublicItem" }, "type": "array", "title": "Ideas" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" }, "meta": { "$ref": "#/components/schemas/ContentIdeasMeta" } }, "type": "object", "required": [ "ideas", "pagination", "meta" ], "title": "ContentIdeasPublicResponse", "description": "GET /content-ideas response." }, "ContentIdeasRefreshRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "action": { "type": "string", "const": "refresh", "title": "Action", "default": "refresh" } }, "type": "object", "required": [ "brand_id" ], "title": "ContentIdeasRefreshRequest", "description": "POST /content-ideas request body." }, "ContentIdeasRefreshResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "message": { "type": "string", "title": "Message" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" } }, "type": "object", "required": [ "status", "message" ], "title": "ContentIdeasRefreshResponse", "description": "POST /content-ideas response." }, "ContentKnowledgePublicResponse": { "properties": { "sources": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Sources" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "additionalProperties": true, "type": "object", "title": "ContentKnowledgePublicResponse" }, "ContentMutationPublicResponse": { "properties": { "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Id" } }, "additionalProperties": true, "type": "object", "title": "ContentMutationPublicResponse" }, "ContentWritingStylePublicResponse": { "properties": { "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Id" }, "style_json": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Style Json" }, "samples": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Samples" }, "sample_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Count" }, "analysis_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis Status" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" } }, "additionalProperties": true, "type": "object", "title": "ContentWritingStylePublicResponse" }, "ConversionValueItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "event_name": { "type": "string", "title": "Event Name" }, "value_per_conversion": { "type": "number", "title": "Value Per Conversion" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "brand_id", "event_name", "value_per_conversion", "created_at", "updated_at" ], "title": "ConversionValueItem" }, "ConversionValuesResponse": { "properties": { "conversions": { "items": { "$ref": "#/components/schemas/ConversionValueItem" }, "type": "array", "title": "Conversions" } }, "type": "object", "required": [ "conversions" ], "title": "ConversionValuesResponse", "description": "GET /traffic/conversions" }, "CrawlerAccessPreviewFixRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "finding_id": { "type": "string", "title": "Finding Id" }, "range_preset": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "custom" ], "title": "Range Preset", "default": "30d" }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" } }, "type": "object", "required": [ "brand_id", "finding_id" ], "title": "CrawlerAccessPreviewFixRequest" }, "CrawlerDashboardResponse": { "properties": { "summary": { "$ref": "#/components/schemas/CrawlerSummaryItem" }, "distribution": { "items": { "$ref": "#/components/schemas/CrawlerDistributionItem" }, "type": "array", "title": "Distribution" }, "time_series": { "items": { "$ref": "#/components/schemas/CrawlerTimeSeriesItem" }, "type": "array", "title": "Time Series" }, "top_pages": { "items": { "$ref": "#/components/schemas/CrawlerTopPageItem" }, "type": "array", "title": "Top Pages" }, "recent_activity": { "items": { "$ref": "#/components/schemas/CrawlerVisitItem" }, "type": "array", "title": "Recent Activity" }, "date_range": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Date Range" } }, "type": "object", "required": [ "summary", "distribution", "time_series", "top_pages", "recent_activity", "date_range" ], "title": "CrawlerDashboardResponse", "description": "GET /get-crawler?view=dashboard response." }, "CrawlerDetailResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "range": { "$ref": "#/components/schemas/CrawlerRangeMeta" }, "kind": { "type": "string", "title": "Kind" }, "entity": { "additionalProperties": true, "type": "object", "title": "Entity" }, "sections": { "additionalProperties": true, "type": "object", "title": "Sections" } }, "type": "object", "required": [ "brand_id", "range", "kind", "entity", "sections" ], "title": "CrawlerDetailResponse" }, "CrawlerDistributionItem": { "properties": { "crawler": { "type": "string", "title": "Crawler" }, "count": { "type": "integer", "title": "Count" }, "percentage": { "type": "number", "title": "Percentage" } }, "type": "object", "required": [ "crawler", "count", "percentage" ], "title": "CrawlerDistributionItem", "description": "Crawler type breakdown." }, "CrawlerListMeta": { "properties": { "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "total", "limit" ], "title": "CrawlerListMeta" }, "CrawlerLiveResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "range": { "$ref": "#/components/schemas/CrawlerRangeMeta" }, "view": { "type": "string", "title": "View" }, "filters": { "additionalProperties": true, "type": "object", "title": "Filters" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "pagination": { "$ref": "#/components/schemas/CrawlerListMeta" } }, "type": "object", "required": [ "brand_id", "range", "view", "filters", "items", "pagination" ], "title": "CrawlerLiveResponse" }, "CrawlerOverviewResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "range": { "$ref": "#/components/schemas/CrawlerRangeMeta" }, "state": { "additionalProperties": true, "type": "object", "title": "State" }, "hero": { "additionalProperties": true, "type": "object", "title": "Hero" }, "chart": { "additionalProperties": true, "type": "object", "title": "Chart" }, "breakdown": { "additionalProperties": true, "type": "object", "title": "Breakdown" }, "top_pages": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Top Pages" }, "recent_preview": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Recent Preview" }, "sessions_preview": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Sessions Preview", "default": [] }, "compare": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Compare" } }, "type": "object", "required": [ "brand_id", "range", "state", "hero", "chart", "breakdown", "top_pages", "recent_preview" ], "title": "CrawlerOverviewResponse" }, "CrawlerPagesResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "range": { "$ref": "#/components/schemas/CrawlerRangeMeta" }, "lens": { "type": "string", "title": "Lens" }, "filters": { "additionalProperties": true, "type": "object", "title": "Filters" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items" }, "pagination": { "$ref": "#/components/schemas/CrawlerListMeta" } }, "type": "object", "required": [ "brand_id", "range", "lens", "filters", "items", "pagination" ], "title": "CrawlerPagesResponse" }, "CrawlerRangeMeta": { "properties": { "range_preset": { "type": "string", "title": "Range Preset" }, "start": { "type": "string", "title": "Start" }, "end": { "type": "string", "title": "End" }, "days": { "type": "integer", "title": "Days" }, "compare_to": { "type": "string", "title": "Compare To", "default": "none" } }, "type": "object", "required": [ "range_preset", "start", "end", "days" ], "title": "CrawlerRangeMeta" }, "CrawlerRecentResponse": { "properties": { "visits": { "items": { "$ref": "#/components/schemas/CrawlerVisitItem" }, "type": "array", "title": "Visits" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "visits", "total" ], "title": "CrawlerRecentResponse", "description": "GET /get-crawler?view=recent response." }, "CrawlerSubmitToSearchRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "urls": { "items": { "type": "string" }, "type": "array", "title": "Urls" } }, "type": "object", "required": [ "brand_id", "urls" ], "title": "CrawlerSubmitToSearchRequest" }, "CrawlerSummaryItem": { "properties": { "total_visits": { "type": "integer", "title": "Total Visits" }, "total_visits_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Visits Change" }, "unique_pages": { "type": "integer", "title": "Unique Pages" }, "unique_pages_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Unique Pages Change" }, "avg_daily_visits": { "type": "number", "title": "Avg Daily Visits" }, "top_crawler": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Top Crawler" } }, "type": "object", "required": [ "total_visits", "unique_pages", "avg_daily_visits" ], "title": "CrawlerSummaryItem", "description": "Summary metrics for crawler dashboard." }, "CrawlerTimeSeriesItem": { "properties": { "date": { "type": "string", "title": "Date" }, "count": { "type": "integer", "title": "Count" }, "by_crawler": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Crawler", "default": {} } }, "type": "object", "required": [ "date", "count" ], "title": "CrawlerTimeSeriesItem", "description": "Time series data point." }, "CrawlerTopPageItem": { "properties": { "url": { "type": "string", "title": "Url" }, "count": { "type": "integer", "title": "Count" }, "crawlers": { "items": { "type": "string" }, "type": "array", "title": "Crawlers", "default": [] } }, "type": "object", "required": [ "url", "count" ], "title": "CrawlerTopPageItem", "description": "Top crawled page." }, "CrawlerVisitItem": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "pathname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pathname" }, "crawler": { "type": "string", "title": "Crawler" }, "visited_at": { "type": "string", "title": "Visited At" } }, "type": "object", "required": [ "id", "url", "crawler", "visited_at" ], "title": "CrawlerVisitItem", "description": "Individual crawler visit." }, "CreatePromptRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "text": { "type": "string", "title": "Text" }, "active": { "type": "boolean", "title": "Active", "default": true }, "focus_area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus Area" }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience" } }, "type": "object", "required": [ "brand_id", "text" ], "title": "CreatePromptRequest", "description": "POST /get-prompts request body." }, "DiagnoseCompetitorApi": { "properties": { "name": { "type": "string", "title": "Name" }, "positions": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object", "title": "Positions", "default": {} }, "score": { "type": "number", "title": "Score", "default": 0 } }, "type": "object", "required": [ "name" ], "title": "DiagnoseCompetitorApi", "description": "Competitor in diagnosis result." }, "DiagnoseHistoryApiResponse": { "properties": { "diagnoses": { "items": { "$ref": "#/components/schemas/DiagnoseSummaryApi" }, "type": "array", "title": "Diagnoses" } }, "type": "object", "required": [ "diagnoses" ], "title": "DiagnoseHistoryApiResponse", "description": "GET /diagnose?view=history response." }, "DiagnoseHypothesisFactorApi": { "properties": { "factor": { "type": "string", "title": "Factor" }, "mentioned_by": { "items": { "type": "string" }, "type": "array", "title": "Mentioned By", "default": [] }, "count": { "type": "integer", "title": "Count", "default": 0 }, "type": { "type": "string", "title": "Type", "default": "" }, "validation_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Validation Status" } }, "type": "object", "required": [ "factor" ], "title": "DiagnoseHypothesisFactorApi", "description": "Hypothesis factor from diagnosis." }, "DiagnoseRecommendationApi": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "gap": { "type": "string", "title": "Gap" }, "effort": { "type": "string", "title": "Effort" }, "impact": { "type": "string", "title": "Impact" }, "validation_status": { "type": "string", "title": "Validation Status" }, "confidence": { "type": "string", "title": "Confidence" }, "mentioned_by_models": { "type": "integer", "title": "Mentioned By Models", "default": 0 } }, "type": "object", "required": [ "id", "title", "gap", "effort", "impact", "validation_status", "confidence" ], "title": "DiagnoseRecommendationApi", "description": "Recommendation from diagnosis." }, "DiagnoseResultApiResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "query": { "type": "string", "title": "Query" }, "status": { "type": "string", "title": "Status" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "visibility_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Score" }, "best_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Best Position" }, "model_positions": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Model Positions" }, "competitors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DiagnoseCompetitorApi" }, "type": "array" }, { "type": "null" } ], "title": "Competitors" }, "model_consistency_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Model Consistency Score" }, "hypothesis_factors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DiagnoseHypothesisFactorApi" }, "type": "array" }, { "type": "null" } ], "title": "Hypothesis Factors" }, "confidence_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Confidence Score" }, "confidence_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence Level" }, "recommendations": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DiagnoseRecommendationApi" }, "type": "array" }, { "type": "null" } ], "title": "Recommendations" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "synthesis_summary": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Synthesis Summary" }, "variant_analysis": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Variant Analysis" }, "phrasing_insight": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Phrasing Insight" }, "visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Change" }, "created_at": { "type": "string", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms" }, "credits_used": { "type": "integer", "title": "Credits Used", "default": 4 }, "models_queried": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Models Queried" }, "models_succeeded": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Models Succeeded" }, "models_failed": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Models Failed" } }, "type": "object", "required": [ "id", "brand_id", "query", "status", "created_at" ], "title": "DiagnoseResultApiResponse", "description": "GET /diagnose?diagnosis_id=X response." }, "DiagnoseRunApiRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "query": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Query", "description": "The search query to diagnose" } }, "type": "object", "required": [ "brand_id", "query" ], "title": "DiagnoseRunApiRequest", "description": "POST /diagnose request body." }, "DiagnoseRunApiResponse": { "properties": { "diagnosis_id": { "type": "string", "title": "Diagnosis Id" }, "status": { "type": "string", "title": "Status", "default": "pending" }, "message": { "type": "string", "title": "Message", "default": "Diagnosis started" } }, "type": "object", "required": [ "diagnosis_id" ], "title": "DiagnoseRunApiResponse", "description": "POST /diagnose response." }, "DiagnoseSummaryApi": { "properties": { "id": { "type": "string", "title": "Id" }, "query": { "type": "string", "title": "Query" }, "visibility_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Score" }, "best_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Best Position" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "title": "Created At" }, "visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Change" } }, "type": "object", "required": [ "id", "query", "status", "created_at" ], "title": "DiagnoseSummaryApi", "description": "Diagnosis summary for history list." }, "DiagnoseUsageApiResponse": { "properties": { "used": { "type": "integer", "title": "Used" }, "limit": { "type": "integer", "title": "Limit" }, "remaining": { "type": "integer", "title": "Remaining" } }, "type": "object", "required": [ "used", "limit", "remaining" ], "title": "DiagnoseUsageApiResponse", "description": "GET /diagnose?view=usage response." }, "ExportResponse": { "properties": { "data_type": { "type": "string", "title": "Data Type" }, "count": { "type": "integer", "title": "Count" }, "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "exported_at": { "type": "string", "title": "Exported At" } }, "type": "object", "required": [ "data_type", "count", "data", "exported_at" ], "title": "ExportResponse", "description": "GET /export JSON response." }, "GenerateReportPublicRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "report_type": { "type": "string", "enum": [ "executive", "weekly", "full" ], "title": "Report Type", "default": "executive" }, "time_range": { "type": "string", "enum": [ "7d", "14d", "30d" ], "title": "Time Range", "default": "7d" } }, "type": "object", "required": [ "brand_id" ], "title": "GenerateReportPublicRequest", "description": "POST /reports request body." }, "GenerateReportPublicResponse": { "properties": { "report_id": { "type": "string", "title": "Report Id" }, "status": { "type": "string", "title": "Status" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Download Url" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "report_id", "status" ], "title": "GenerateReportPublicResponse", "description": "POST /reports response." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HistoricalPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" }, "mentions": { "type": "integer", "title": "Mentions", "default": 0 } }, "type": "object", "required": [ "date", "visibility", "presence" ], "title": "HistoricalPoint", "description": "Historical data point." }, "LatestScores": { "properties": { "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" }, "mentions": { "type": "integer", "title": "Mentions", "default": 0 }, "models_mentioned": { "type": "integer", "title": "Models Mentioned", "default": 0 }, "model_scores": { "additionalProperties": { "$ref": "#/components/schemas/ModelScore" }, "type": "object", "title": "Model Scores", "default": {} }, "date": { "type": "string", "title": "Date" } }, "type": "object", "required": [ "visibility", "presence", "date" ], "title": "LatestScores", "description": "Latest visibility metrics." }, "ManageActionRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "action_id": { "type": "string", "title": "Action Id" }, "action": { "type": "string", "title": "Action" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" }, "snooze_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snooze Until" }, "assignee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee" } }, "type": "object", "required": [ "brand_id", "action_id", "action" ], "title": "ManageActionRequest", "description": "POST /manage-action request." }, "ManageActionResponse": { "properties": { "ok": { "type": "boolean", "title": "Ok" }, "action": { "anyOf": [ { "$ref": "#/components/schemas/ActionPublicItem" }, { "type": "null" } ] }, "note_added": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Note Added" } }, "type": "object", "required": [ "ok" ], "title": "ManageActionResponse", "description": "POST /manage-action response." }, "ManageCompetitorRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "action": { "type": "string", "enum": [ "list", "add", "remove", "hide", "unhide" ], "title": "Action" }, "competitor": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Competitor" } }, "type": "object", "required": [ "brand_id", "action" ], "title": "ManageCompetitorRequest", "description": "POST /competitors/manage body." }, "ManagePromptTagsRequest": { "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete", "add", "remove" ], "title": "Action" }, "brand_id": { "type": "string", "title": "Brand Id" }, "tag_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tag Id" }, "tag_name": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ], "title": "Tag Name" }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Colour" }, "prompt_ids": { "items": { "type": "string" }, "type": "array", "maxItems": 200, "title": "Prompt Ids" }, "create_if_missing": { "type": "boolean", "title": "Create If Missing", "default": true } }, "type": "object", "required": [ "action", "brand_id" ], "title": "ManagePromptTagsRequest", "description": "POST /manage-prompt-tags request body." }, "ManagePromptTagsResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "action": { "type": "string", "title": "Action" }, "tag": { "$ref": "#/components/schemas/TagItem" }, "created": { "type": "boolean", "title": "Created", "default": false }, "affected_prompt_ids": { "items": { "type": "string" }, "type": "array", "title": "Affected Prompt Ids" }, "affected_count": { "type": "integer", "title": "Affected Count", "default": 0 }, "unchanged_count": { "type": "integer", "title": "Unchanged Count", "default": 0 } }, "type": "object", "required": [ "success", "action", "tag" ], "title": "ManagePromptTagsResponse", "description": "POST /manage-prompt-tags response." }, "MarketItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "location": { "type": "string", "title": "Location" }, "location_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Region" }, "location_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location City" }, "is_primary": { "type": "boolean", "title": "Is Primary" }, "active": { "type": "boolean", "title": "Active" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "brand_id", "location", "is_primary", "active", "created_at" ], "title": "MarketItem", "description": "Market in brand response." }, "MentionsTimeSeriesPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "mentions": { "type": "integer", "title": "Mentions" }, "models_mentioned": { "type": "integer", "title": "Models Mentioned", "default": 0 } }, "type": "object", "required": [ "date", "mentions" ], "title": "MentionsTimeSeriesPoint" }, "ModelPerformance": { "properties": { "model": { "type": "string", "title": "Model" }, "total_queries": { "type": "integer", "title": "Total Queries" }, "mentions": { "type": "integer", "title": "Mentions" }, "visibility_rate": { "type": "number", "title": "Visibility Rate" }, "average_position": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Position" }, "top_3_rate": { "type": "number", "title": "Top 3 Rate" }, "top_3_count": { "type": "integer", "title": "Top 3 Count" } }, "type": "object", "required": [ "model", "total_queries", "mentions", "visibility_rate", "top_3_rate", "top_3_count" ], "title": "ModelPerformance", "description": "Model performance metrics." }, "ModelScore": { "properties": { "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" } }, "type": "object", "required": [ "visibility", "presence" ], "title": "ModelScore", "description": "Per-model score breakdown." }, "ModelsResponse": { "properties": { "models": { "items": { "$ref": "#/components/schemas/ModelPerformance" }, "type": "array", "title": "Models" }, "summary": { "$ref": "#/components/schemas/ModelsSummary" } }, "type": "object", "required": [ "models", "summary" ], "title": "ModelsResponse", "description": "GET /get-models response." }, "ModelsSummary": { "properties": { "total_results": { "type": "integer", "title": "Total Results" }, "total_mentions": { "type": "integer", "title": "Total Mentions" }, "overall_visibility_rate": { "type": "number", "title": "Overall Visibility Rate" }, "model_count": { "type": "integer", "title": "Model Count" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "total_results", "total_mentions", "overall_visibility_rate", "model_count", "period_days" ], "title": "ModelsSummary", "description": "Models summary." }, "NarrativeCorrectiveApi": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "key_phrases": { "items": { "type": "string" }, "type": "array", "title": "Key Phrases", "default": [] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "name" ], "title": "NarrativeCorrectiveApi", "description": "Narrative corrective item." }, "NarrativeCreateApiRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "description": { "type": "string", "maxLength": 2000, "minLength": 1, "title": "Description" }, "keywords": { "items": { "type": "string" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Keywords" }, "comparison_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison Brand" } }, "type": "object", "required": [ "brand_id", "name", "description", "keywords" ], "title": "NarrativeCreateApiRequest", "description": "POST /narratives request body." }, "NarrativeCreateApiResponse": { "properties": { "narrative_id": { "type": "string", "title": "Narrative Id" }, "status": { "type": "string", "title": "Status", "default": "created" }, "message": { "type": "string", "title": "Message", "default": "Narrative created and first analysis started" } }, "type": "object", "required": [ "narrative_id" ], "title": "NarrativeCreateApiResponse", "description": "POST /narratives response." }, "NarrativeDeleteApiResponse": { "properties": { "narrative_id": { "type": "string", "title": "Narrative Id" }, "status": { "type": "string", "title": "Status", "default": "archived" } }, "type": "object", "required": [ "narrative_id" ], "title": "NarrativeDeleteApiResponse", "description": "DELETE /narratives response." }, "NarrativeItemApi": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "keywords": { "items": { "type": "string" }, "type": "array", "title": "Keywords", "default": [] }, "comparison_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison Brand" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "title": "Created At" }, "latest_snapshot": { "anyOf": [ { "$ref": "#/components/schemas/NarrativeSnapshotApi" }, { "type": "null" } ] }, "correctives": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NarrativeCorrectiveApi" }, "type": "array" }, { "type": "null" } ], "title": "Correctives" }, "snapshots": { "anyOf": [ { "items": { "$ref": "#/components/schemas/NarrativeSnapshotApi" }, "type": "array" }, { "type": "null" } ], "title": "Snapshots" } }, "type": "object", "required": [ "id", "brand_id", "name", "description", "status", "created_at" ], "title": "NarrativeItemApi", "description": "Narrative in the API response." }, "NarrativeSnapshotApi": { "properties": { "id": { "type": "string", "title": "Id" }, "run_date": { "type": "string", "title": "Run Date" }, "run_type": { "type": "string", "title": "Run Type" }, "overall_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Overall Score" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "comparison_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Comparison Score" }, "themes": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Themes" } }, "type": "object", "required": [ "id", "run_date", "run_type" ], "title": "NarrativeSnapshotApi", "description": "Narrative snapshot summary." }, "NarrativeUpdateApiRequest": { "properties": { "narrative_id": { "type": "string", "title": "Narrative Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000, "minLength": 1 }, { "type": "null" } ], "title": "Description" }, "keywords": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 10, "minItems": 1 }, { "type": "null" } ], "title": "Keywords" }, "comparison_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison Brand" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, "type": "object", "required": [ "narrative_id" ], "title": "NarrativeUpdateApiRequest", "description": "PATCH /narratives request body." }, "NarrativeUpdateApiResponse": { "properties": { "narrative_id": { "type": "string", "title": "Narrative Id" }, "status": { "type": "string", "title": "Status", "default": "updated" } }, "type": "object", "required": [ "narrative_id" ], "title": "NarrativeUpdateApiResponse", "description": "PATCH /narratives response." }, "NarrativesListApiResponse": { "properties": { "narratives": { "items": { "$ref": "#/components/schemas/NarrativeItemApi" }, "type": "array", "title": "Narratives" } }, "type": "object", "required": [ "narratives" ], "title": "NarrativesListApiResponse", "description": "GET /narratives response (list)." }, "NotificationsMarkReadRequest": { "properties": { "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Id" }, "notification_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Notification Ids" }, "mark_all": { "type": "boolean", "title": "Mark All", "default": false } }, "type": "object", "title": "NotificationsMarkReadRequest", "description": "POST /notifications/read body." }, "NotificationsPublicResponse": { "properties": { "notifications": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Notifications" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "unread_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unread Count" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" }, "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Id" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" } }, "additionalProperties": true, "type": "object", "title": "NotificationsPublicResponse" }, "NotificationsReadResponse": { "properties": { "updated_count": { "type": "integer", "title": "Updated Count" } }, "type": "object", "required": [ "updated_count" ], "title": "NotificationsReadResponse" }, "OpportunitiesResponse": { "properties": { "opportunities": { "items": { "$ref": "#/components/schemas/OpportunityItem" }, "type": "array", "title": "Opportunities" }, "summary": { "$ref": "#/components/schemas/OpportunitiesSummary" }, "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "required": [ "opportunities", "summary", "brand" ], "title": "OpportunitiesResponse", "description": "GET /get-opportunities response." }, "OpportunitiesSummary": { "properties": { "total_opportunities": { "type": "integer", "title": "Total Opportunities" }, "not_mentioned_count": { "type": "integer", "title": "Not Mentioned Count" }, "uncited_count": { "type": "integer", "title": "Uncited Count" }, "low_position_count": { "type": "integer", "title": "Low Position Count" }, "period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Period Days" } }, "type": "object", "required": [ "total_opportunities", "not_mentioned_count", "uncited_count", "low_position_count" ], "title": "OpportunitiesSummary", "description": "Opportunities summary." }, "OpportunityItem": { "properties": { "result_id": { "type": "string", "title": "Result Id" }, "prompt_text": { "type": "string", "title": "Prompt Text" }, "llm": { "type": "string", "title": "Llm" }, "date": { "type": "string", "title": "Date" }, "competitors": { "items": { "$ref": "#/components/schemas/CompetitorPosition" }, "type": "array", "title": "Competitors" }, "opportunity_type": { "type": "string", "title": "Opportunity Type" }, "priority": { "type": "string", "title": "Priority" }, "reason": { "type": "string", "title": "Reason" } }, "type": "object", "required": [ "result_id", "prompt_text", "llm", "date", "competitors", "opportunity_type", "priority", "reason" ], "title": "OpportunityItem", "description": "Opportunity item." }, "OpportunityPoolResponse": { "properties": { "opportunities": { "items": { "$ref": "#/components/schemas/OpportunityPublicItem" }, "type": "array", "title": "Opportunities" }, "meta": { "$ref": "#/components/schemas/UnityListMeta" } }, "type": "object", "required": [ "opportunities", "meta" ], "title": "OpportunityPoolResponse" }, "OpportunityPublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "kind": { "type": "string", "title": "Kind" }, "family": { "type": "string", "title": "Family" }, "title": { "type": "string", "title": "Title" }, "impact": { "type": "string", "title": "Impact" }, "status": { "type": "string", "title": "Status" }, "evidence": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Evidence", "default": [] }, "page_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Id" }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Url" }, "dedup_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dedup Key" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "kind", "family", "title", "impact", "status", "created_at" ], "title": "OpportunityPublicItem", "description": "One suggestion from the pool. Renders as \"Suggested\" in-product; the\nword \"opportunity\" is the schema's, not the user's." }, "PageAnalysesListResponse": { "properties": { "analyses": { "items": { "$ref": "#/components/schemas/PageAnalysisListItem" }, "type": "array", "title": "Analyses" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "analyses", "total" ], "title": "PageAnalysesListResponse", "description": "GET /get-page-analyses list response." }, "PageAnalysisDetailResponse": { "properties": { "url": { "type": "string", "title": "Url" }, "analyzed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analyzed At" }, "cached": { "type": "boolean", "title": "Cached", "default": true }, "ai_diagnosis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Diagnosis" }, "overall_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Overall Score" }, "technical_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Technical Score" }, "citation_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Citation Score" }, "citation_verdict": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Citation Verdict" }, "single_top_fix": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Single Top Fix" }, "secondary_fixes": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Secondary Fixes", "default": [] }, "detected_queries": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Detected Queries", "default": [] }, "quotable_facts": { "items": {}, "type": "array", "title": "Quotable Facts", "default": [] }, "ready_to_paste_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Ready To Paste Schema" }, "technical_checks": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Technical Checks" }, "failed_checks": { "items": { "type": "string" }, "type": "array", "title": "Failed Checks", "default": [] }, "warning_checks": { "items": { "type": "string" }, "type": "array", "title": "Warning Checks", "default": [] }, "entities": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Entities", "default": [] }, "detected_cms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detected Cms" }, "bot_visibility": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Bot Visibility" } }, "type": "object", "required": [ "url" ], "title": "PageAnalysisDetailResponse", "description": "GET /get-page-analyses?url=\u2026 detail response.\n\nMirrors the shape stored in page_analyses.raw_analysis / materialized columns." }, "PageAnalysisListItem": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "analyzed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analyzed At" }, "overall_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Overall Score" }, "technical_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Technical Score" }, "citation_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Citation Score" }, "page_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Type" }, "failed_checks_count": { "type": "integer", "title": "Failed Checks Count", "default": 0 }, "is_stale": { "type": "boolean", "title": "Is Stale", "default": false } }, "type": "object", "required": [ "id", "url" ], "title": "PageAnalysisListItem", "description": "Summary row for the recent page analyses listing." }, "PagePublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "slug": { "type": "string", "title": "Slug" }, "ownership": { "type": "string", "title": "Ownership" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "tracked": { "type": "boolean", "title": "Tracked", "default": false }, "bottleneck": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bottleneck" }, "verdict": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Verdict" }, "last_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen At" } }, "type": "object", "required": [ "id", "url", "slug", "ownership" ], "title": "PagePublicItem" }, "PagesResponse": { "properties": { "pages": { "items": { "$ref": "#/components/schemas/PagePublicItem" }, "type": "array", "title": "Pages" }, "meta": { "$ref": "#/components/schemas/UnityListMeta" } }, "type": "object", "required": [ "pages", "meta" ], "title": "PagesResponse" }, "PaginationInfo": { "properties": { "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "total", "limit", "offset", "has_more" ], "title": "PaginationInfo", "description": "Pagination metadata." }, "PerceptionBrandSummaryApi": { "properties": { "brand_name": { "type": "string", "title": "Brand Name" }, "is_primary": { "type": "boolean", "title": "Is Primary", "default": false }, "rank_1_in": { "items": { "type": "string" }, "type": "array", "title": "Rank 1 In", "default": [] }, "rank_last_in": { "items": { "type": "string" }, "type": "array", "title": "Rank Last In", "default": [] } }, "type": "object", "required": [ "brand_name" ], "title": "PerceptionBrandSummaryApi", "description": "Summary for a tracked brand." }, "PerceptionBrandTimeSeriesApi": { "properties": { "brand_name": { "type": "string", "title": "Brand Name" }, "is_primary": { "type": "boolean", "title": "Is Primary", "default": false }, "metrics": { "items": { "$ref": "#/components/schemas/PerceptionMetricTimeSeriesApi" }, "type": "array", "title": "Metrics", "default": [] } }, "type": "object", "required": [ "brand_name" ], "title": "PerceptionBrandTimeSeriesApi", "description": "All metric time series for a brand." }, "PerceptionCompetitorGapApi": { "properties": { "competitor": { "type": "string", "title": "Competitor" }, "your_advantages": { "items": { "type": "string" }, "type": "array", "title": "Your Advantages", "default": [] }, "their_advantages": { "items": { "type": "string" }, "type": "array", "title": "Their Advantages", "default": [] }, "biggest_gap_for_you": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Biggest Gap For You" }, "biggest_gap_against_you": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Biggest Gap Against You" } }, "type": "object", "required": [ "competitor" ], "title": "PerceptionCompetitorGapApi", "description": "Competitor gap analysis." }, "PerceptionDashboardApiResponse": { "properties": { "metadata": { "$ref": "#/components/schemas/PerceptionMetadataApi" }, "perception_score": { "$ref": "#/components/schemas/PerceptionScoreApi" }, "category_scores": { "additionalProperties": true, "type": "object", "title": "Category Scores", "default": {} }, "insights": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object", "title": "Insights", "default": {} }, "brand_summaries": { "items": { "$ref": "#/components/schemas/PerceptionBrandSummaryApi" }, "type": "array", "title": "Brand Summaries", "default": [] }, "detailed_sentiment_timeseries": { "items": { "$ref": "#/components/schemas/PerceptionBrandTimeSeriesApi" }, "type": "array", "title": "Detailed Sentiment Timeseries", "default": [] }, "competitor_gaps": { "items": { "$ref": "#/components/schemas/PerceptionCompetitorGapApi" }, "type": "array", "title": "Competitor Gaps", "default": [] }, "radar_chart_data": { "items": { "$ref": "#/components/schemas/PerceptionRadarBrandApi" }, "type": "array", "title": "Radar Chart Data", "default": [] }, "metric_rankings": { "additionalProperties": true, "type": "object", "title": "Metric Rankings", "default": {} }, "primary_brand_overall_timeseries": { "items": { "$ref": "#/components/schemas/PerceptionMetricSeriesPointApi" }, "type": "array", "title": "Primary Brand Overall Timeseries", "default": [] } }, "type": "object", "required": [ "metadata", "perception_score" ], "title": "PerceptionDashboardApiResponse", "description": "GET /get-perception?view=dashboard response." }, "PerceptionMetadataApi": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "primary_brand": { "type": "string", "title": "Primary Brand" }, "date_range_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date Range Start" }, "date_range_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Date Range End" }, "total_brands_tracked": { "type": "integer", "title": "Total Brands Tracked", "default": 0 }, "days_of_data": { "type": "integer", "title": "Days Of Data", "default": 0 } }, "type": "object", "required": [ "brand_id", "primary_brand" ], "title": "PerceptionMetadataApi", "description": "Metadata for perception dashboard response." }, "PerceptionMetricSeriesPointApi": { "properties": { "date": { "type": "string", "title": "Date" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" } }, "type": "object", "required": [ "date" ], "title": "PerceptionMetricSeriesPointApi", "description": "Single data point in a metric time series." }, "PerceptionMetricTimeSeriesApi": { "properties": { "metric_name": { "type": "string", "title": "Metric Name" }, "series": { "items": { "$ref": "#/components/schemas/PerceptionMetricSeriesPointApi" }, "type": "array", "title": "Series", "default": [] }, "average_7_day": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average 7 Day" } }, "type": "object", "required": [ "metric_name" ], "title": "PerceptionMetricTimeSeriesApi", "description": "Time series for a single metric." }, "PerceptionMetricsApiResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "tracked_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tracked Brand" }, "days": { "type": "integer", "title": "Days" }, "count": { "type": "integer", "title": "Count" }, "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data", "default": [] } }, "type": "object", "required": [ "brand_id", "days", "count" ], "title": "PerceptionMetricsApiResponse", "description": "GET /get-perception?view=metrics response." }, "PerceptionNarrativeApiResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "narrative": { "anyOf": [ { "$ref": "#/components/schemas/PerceptionNarrativeData" }, { "type": "null" } ] }, "snapshot_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snapshot Date" } }, "type": "object", "required": [ "brand_id" ], "title": "PerceptionNarrativeApiResponse", "description": "GET /get-perception?view=narrative response." }, "PerceptionNarrativeData": { "properties": { "positioning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Positioning" }, "strengths": { "items": { "type": "string" }, "type": "array", "title": "Strengths", "default": [] }, "weaknesses": { "items": { "type": "string" }, "type": "array", "title": "Weaknesses", "default": [] }, "opportunities": { "items": { "type": "string" }, "type": "array", "title": "Opportunities", "default": [] }, "sentiment_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment Summary" } }, "type": "object", "title": "PerceptionNarrativeData", "description": "Perception narrative analysis data." }, "PerceptionRadarBrandApi": { "properties": { "name": { "type": "string", "title": "Name" }, "is_primary": { "type": "boolean", "title": "Is Primary", "default": false }, "data": { "items": { "$ref": "#/components/schemas/PerceptionRadarPointApi" }, "type": "array", "title": "Data", "default": [] } }, "type": "object", "required": [ "name" ], "title": "PerceptionRadarBrandApi", "description": "Radar chart data for a brand." }, "PerceptionRadarPointApi": { "properties": { "axis": { "type": "string", "title": "Axis" }, "value": { "type": "number", "title": "Value" } }, "type": "object", "required": [ "axis", "value" ], "title": "PerceptionRadarPointApi", "description": "Radar chart data point." }, "PerceptionRunApiResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "brand_id": { "type": "string", "title": "Brand Id" }, "primary_brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Brand" }, "run_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Date" }, "brands_analyzed": { "items": { "type": "string" }, "type": "array", "title": "Brands Analyzed", "default": [] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "status", "brand_id" ], "title": "PerceptionRunApiResponse", "description": "POST /get-perception response." }, "PerceptionRunRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "include_competitors": { "type": "boolean", "title": "Include Competitors", "default": true } }, "type": "object", "required": [ "brand_id" ], "title": "PerceptionRunRequest", "description": "POST /get-perception request body." }, "PerceptionScoreApi": { "properties": { "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Score" }, "change_7d": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Change 7D" }, "percentile": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percentile" } }, "type": "object", "title": "PerceptionScoreApi", "description": "Perception score summary." }, "PortfolioActionsPublicResponse": { "properties": { "actions": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Actions" }, "total": { "type": "integer", "title": "Total" }, "brand_count": { "type": "integer", "title": "Brand Count" }, "group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group Id" }, "quick_win_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Quick Win Only" } }, "additionalProperties": true, "type": "object", "required": [ "actions", "total", "brand_count" ], "title": "PortfolioActionsPublicResponse" }, "PrismPublicConfig": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "domain": { "type": "string", "title": "Domain" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform" }, "features": { "items": { "type": "string" }, "type": "array", "title": "Features", "default": [] }, "crawlers": { "items": { "type": "string" }, "type": "array", "title": "Crawlers", "default": [] } }, "type": "object", "required": [ "enabled", "domain" ], "title": "PrismPublicConfig", "description": "AI Pages configuration." }, "PrismPublicUsage": { "properties": { "requests_this_month": { "type": "integer", "title": "Requests This Month" }, "requests_limit": { "type": "integer", "title": "Requests Limit" }, "percentage_used": { "type": "number", "title": "Percentage Used" }, "reset_date": { "type": "string", "title": "Reset Date" } }, "type": "object", "required": [ "requests_this_month", "requests_limit", "percentage_used", "reset_date" ], "title": "PrismPublicUsage", "description": "AI Pages usage stats." }, "PrismResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/PrismPublicConfig" }, { "type": "null" } ] }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/PrismPublicUsage" }, { "type": "null" } ] } }, "type": "object", "required": [ "brand" ], "title": "PrismResponse", "description": "GET /ai-pages response." }, "PromptItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "text": { "type": "string", "title": "Text" }, "active": { "type": "boolean", "title": "Active", "default": true }, "focus_area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus Area" }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience" }, "specificity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Specificity" }, "quality_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quality Score" }, "source": { "type": "string", "title": "Source", "default": "api" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "tags": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TagItem" }, "type": "array" }, { "type": "null" } ], "title": "Tags" } }, "type": "object", "required": [ "id", "brand_id", "text", "created_at" ], "title": "PromptItem", "description": "Prompt in API response." }, "PromptMarketScore": { "properties": { "market_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Market Id" }, "location": { "type": "string", "title": "Location" }, "location_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Region" }, "location_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location City" }, "is_primary": { "type": "boolean", "title": "Is Primary" }, "score": { "type": "number", "title": "Score" }, "search_volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Search Volume" }, "priority_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Priority Score" } }, "type": "object", "required": [ "location", "is_primary", "score" ], "title": "PromptMarketScore" }, "PromptRanking": { "properties": { "prompt_id": { "type": "string", "title": "Prompt Id" }, "prompt_text": { "type": "string", "title": "Prompt Text" }, "markets": { "items": { "$ref": "#/components/schemas/PromptMarketScore" }, "type": "array", "title": "Markets" } }, "type": "object", "required": [ "prompt_id", "prompt_text", "markets" ], "title": "PromptRanking" }, "PromptsListResponse": { "properties": { "prompts": { "items": { "$ref": "#/components/schemas/PromptItem" }, "type": "array", "title": "Prompts" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "prompts", "total", "limit", "offset" ], "title": "PromptsListResponse", "description": "GET /get-prompts response." }, "ProofResponse": { "properties": { "proof": { "items": { "$ref": "#/components/schemas/ResultPublicItem" }, "type": "array", "title": "Proof" }, "meta": { "$ref": "#/components/schemas/UnityListMeta" }, "verdict_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Verdict Counts" } }, "type": "object", "required": [ "proof", "meta", "verdict_counts" ], "title": "ProofResponse" }, "PublicApiErrorResponse": { "properties": { "detail": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "title": "PublicApiErrorResponse", "description": "Stable public error envelope, including the rate-limiter variant." }, "PublicDeleteResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "deleted_id": { "type": "string", "title": "Deleted Id" } }, "type": "object", "required": [ "success", "deleted_id" ], "title": "PublicDeleteResponse" }, "PublicGenerateArticleRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "primary_prompt": { "type": "string", "title": "Primary Prompt" }, "secondary_prompts": { "items": { "type": "string" }, "type": "array", "title": "Secondary Prompts" }, "word_target": { "type": "integer", "maximum": 6000.0, "minimum": 300.0, "title": "Word Target", "default": 2000 }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Template Id" } }, "type": "object", "required": [ "brand_id", "primary_prompt" ], "title": "PublicGenerateArticleRequest", "description": "POST /content/articles/generate body." }, "PublicKnowledgeTextRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "name": { "type": "string", "title": "Name" }, "content": { "type": "string", "title": "Content" } }, "type": "object", "required": [ "brand_id", "name", "content" ], "title": "PublicKnowledgeTextRequest", "description": "POST /content/knowledge/sources/text body." }, "PublicKnowledgeUrlRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "url": { "type": "string", "title": "Url" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "brand_id", "url" ], "title": "PublicKnowledgeUrlRequest", "description": "POST /content/knowledge/sources/url body." }, "RankedBrand": { "properties": { "rank": { "type": "integer", "title": "Rank" }, "name": { "type": "string", "title": "Name" }, "visibility": { "type": "number", "title": "Visibility" }, "visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Change" }, "is_you": { "type": "boolean", "title": "Is You", "default": false }, "h2h_win_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "H2H Win Rate" } }, "type": "object", "required": [ "rank", "name", "visibility" ], "title": "RankedBrand" }, "RankingsByPromptResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "prompts": { "items": { "$ref": "#/components/schemas/PromptRanking" }, "type": "array", "title": "Prompts" } }, "type": "object", "required": [ "brand", "prompts" ], "title": "RankingsByPromptResponse", "description": "GET /get-rankings?view=by-prompt" }, "RankingsOverallResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "your_rank": { "type": "integer", "title": "Your Rank" }, "total_competitors": { "type": "integer", "title": "Total Competitors" }, "your_visibility": { "type": "number", "title": "Your Visibility" }, "your_visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Your Visibility Change" }, "win_rate": { "type": "number", "title": "Win Rate" }, "threat_count": { "type": "integer", "title": "Threat Count" }, "rankings": { "items": { "$ref": "#/components/schemas/RankedBrand" }, "type": "array", "title": "Rankings" }, "days_requested": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Requested" }, "days_effective": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Effective" }, "window_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Window Note" } }, "type": "object", "required": [ "brand", "your_rank", "total_competitors", "your_visibility", "win_rate", "threat_count", "rankings" ], "title": "RankingsOverallResponse", "description": "GET /get-rankings (default)" }, "RedditMutationResponse": { "properties": { "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Id" } }, "additionalProperties": true, "type": "object", "title": "RedditMutationResponse" }, "RedditOpportunityDismissRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "is_dismissed": { "type": "boolean", "title": "Is Dismissed", "default": true } }, "type": "object", "required": [ "brand_id" ], "title": "RedditOpportunityDismissRequest" }, "RedditOpportunityRespondRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" } }, "type": "object", "required": [ "brand_id" ], "title": "RedditOpportunityRespondRequest" }, "RedditPublicResponse": { "properties": { "brand_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Id" }, "items": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Items" }, "subreddits": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Subreddits" }, "triggers": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Triggers" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "has_more": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has More" } }, "additionalProperties": true, "type": "object", "title": "RedditPublicResponse" }, "RedditScanRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "max_threads": { "type": "integer", "maximum": 120.0, "minimum": 10.0, "title": "Max Threads", "default": 40 } }, "type": "object", "required": [ "brand_id" ], "title": "RedditScanRequest" }, "RedditSubredditAddRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "subreddit_name": { "type": "string", "maxLength": 60, "minLength": 1, "title": "Subreddit Name" } }, "type": "object", "required": [ "brand_id", "subreddit_name" ], "title": "RedditSubredditAddRequest" }, "RedditTriggerAddRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "keyword": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Keyword" } }, "type": "object", "required": [ "brand_id", "keyword" ], "title": "RedditTriggerAddRequest" }, "ReportCompareRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "baseline": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Baseline" }, "comparison": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Comparison" } }, "type": "object", "required": [ "brand_id", "baseline", "comparison" ], "title": "ReportCompareRequest" }, "ReportCompareResponse": { "properties": { "baseline": { "$ref": "#/components/schemas/ReportPeriodMetrics" }, "comparison": { "$ref": "#/components/schemas/ReportPeriodMetrics" }, "deltas": { "$ref": "#/components/schemas/ReportDeltas" }, "drivers": { "items": { "$ref": "#/components/schemas/ReportPromptChange" }, "type": "array", "title": "Drivers" }, "drops": { "items": { "$ref": "#/components/schemas/ReportPromptChange" }, "type": "array", "title": "Drops" } }, "type": "object", "required": [ "baseline", "comparison", "deltas", "drivers", "drops" ], "title": "ReportCompareResponse", "description": "POST /get-reports/compare" }, "ReportDelta": { "properties": { "value": { "type": "number", "title": "Value" }, "percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Percent" }, "improved": { "type": "boolean", "title": "Improved" } }, "type": "object", "required": [ "value", "improved" ], "title": "ReportDelta" }, "ReportDeltas": { "properties": { "visibility": { "$ref": "#/components/schemas/ReportDelta" }, "presence": { "$ref": "#/components/schemas/ReportDelta" }, "average_rank": { "anyOf": [ { "$ref": "#/components/schemas/ReportDelta" }, { "type": "null" } ] } }, "type": "object", "required": [ "visibility", "presence" ], "title": "ReportDeltas" }, "ReportDetailPublic": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "report_type": { "type": "string", "title": "Report Type" }, "report_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Name" }, "time_range": { "type": "string", "title": "Time Range", "default": "7d" }, "status": { "type": "string", "title": "Status", "default": "pending" }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size Bytes" }, "page_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Count" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "created_at": { "type": "string", "title": "Created At" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "report_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Report Data" } }, "type": "object", "required": [ "id", "brand_id", "report_type", "created_at" ], "title": "ReportDetailPublic", "description": "Single report with full data snapshot." }, "ReportMentionsResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "time_series": { "items": { "$ref": "#/components/schemas/MentionsTimeSeriesPoint" }, "type": "array", "title": "Time Series" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "brand", "time_series", "period_days" ], "title": "ReportMentionsResponse", "description": "GET /get-reports?view=mentions_time_series" }, "ReportModelScore": { "properties": { "model": { "type": "string", "title": "Model" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "mentions": { "type": "integer", "title": "Mentions", "default": 0 } }, "type": "object", "required": [ "model", "visibility", "presence" ], "title": "ReportModelScore" }, "ReportPeriodMetrics": { "properties": { "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" }, "report_count": { "type": "integer", "title": "Report Count" }, "date_range": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Date Range" } }, "type": "object", "required": [ "visibility", "presence", "report_count", "date_range" ], "title": "ReportPeriodMetrics" }, "ReportPromptChange": { "properties": { "prompt_text": { "type": "string", "title": "Prompt Text" }, "change": { "type": "number", "title": "Change" } }, "type": "object", "required": [ "prompt_text", "change" ], "title": "ReportPromptChange" }, "ReportPromptScore": { "properties": { "prompt_text": { "type": "string", "title": "Prompt Text" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" } }, "type": "object", "required": [ "prompt_text", "visibility", "presence" ], "title": "ReportPromptScore" }, "ReportPublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "report_type": { "type": "string", "title": "Report Type" }, "report_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Name" }, "time_range": { "type": "string", "title": "Time Range", "default": "7d" }, "status": { "type": "string", "title": "Status", "default": "pending" }, "file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Url" }, "file_size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "File Size Bytes" }, "page_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Count" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message" }, "created_at": { "type": "string", "title": "Created At" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "id", "brand_id", "report_type", "created_at" ], "title": "ReportPublicItem", "description": "Public API representation of a generated report." }, "ReportResultsResponse": { "properties": { "report_id": { "type": "string", "title": "Report Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "date": { "type": "string", "title": "Date" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" }, "model_scores": { "items": { "$ref": "#/components/schemas/ReportModelScore" }, "type": "array", "title": "Model Scores" }, "prompt_scores": { "items": { "$ref": "#/components/schemas/ReportPromptScore" }, "type": "array", "title": "Prompt Scores" } }, "type": "object", "required": [ "report_id", "brand_id", "date", "visibility", "presence", "model_scores", "prompt_scores" ], "title": "ReportResultsResponse", "description": "GET /get-reports?view=results" }, "ReportSentimentResponse": { "properties": { "brand": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Brand" }, "distribution": { "$ref": "#/components/schemas/SentimentDistribution" }, "trend": { "items": { "$ref": "#/components/schemas/SentimentTrendPoint" }, "type": "array", "title": "Trend" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "brand", "distribution", "trend", "period_days" ], "title": "ReportSentimentResponse", "description": "GET /get-reports?view=sentiment" }, "ReportSinglePublicResponse": { "properties": { "report": { "$ref": "#/components/schemas/ReportDetailPublic" } }, "type": "object", "required": [ "report" ], "title": "ReportSinglePublicResponse", "description": "GET /reports response (single report mode)." }, "ReportsListPublicResponse": { "properties": { "reports": { "items": { "$ref": "#/components/schemas/ReportPublicItem" }, "type": "array", "title": "Reports" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } }, "type": "object", "required": [ "reports", "pagination" ], "title": "ReportsListPublicResponse", "description": "GET /reports response (list mode)." }, "RerunPromptRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "prompt_id": { "type": "string", "title": "Prompt Id" } }, "type": "object", "required": [ "brand_id", "prompt_id" ], "title": "RerunPromptRequest" }, "RerunPromptResponse": { "properties": { "queued": { "type": "boolean", "title": "Queued" }, "prompt_id": { "type": "string", "title": "Prompt Id" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "queued", "prompt_id", "message" ], "title": "RerunPromptResponse" }, "ResearchRunDetailResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "ready": { "type": "boolean", "title": "Ready", "default": false }, "report_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Type" }, "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic" }, "topic_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Context" }, "primary_brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Brand Name" }, "competitors": { "items": { "type": "string" }, "type": "array", "title": "Competitors" }, "summary": { "additionalProperties": true, "type": "object", "title": "Summary" }, "visibility": { "additionalProperties": true, "type": "object", "title": "Visibility" }, "position_distribution": { "additionalProperties": true, "type": "object", "title": "Position Distribution" }, "competitors_breakdown": { "additionalProperties": true, "type": "object", "title": "Competitors Breakdown" }, "intent_breakdown": { "additionalProperties": true, "type": "object", "title": "Intent Breakdown" }, "focus_area_breakdown": { "additionalProperties": true, "type": "object", "title": "Focus Area Breakdown" }, "topic_breakdown": { "additionalProperties": true, "type": "object", "title": "Topic Breakdown" }, "insights": { "additionalProperties": true, "type": "object", "title": "Insights" }, "market": { "additionalProperties": true, "type": "object", "title": "Market" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Results" }, "results_truncated": { "type": "boolean", "title": "Results Truncated", "default": false }, "total_results": { "type": "integer", "title": "Total Results", "default": 0 } }, "type": "object", "required": [ "id", "brand_id", "created_at" ], "title": "ResearchRunDetailResponse", "description": "Full prompt_reports row including the analytics payload and per-prompt results." }, "ResearchRunListItem": { "properties": { "id": { "type": "string", "title": "Id" }, "brand_id": { "type": "string", "title": "Brand Id" }, "created_at": { "type": "string", "title": "Created At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "ready": { "type": "boolean", "title": "Ready", "default": false }, "report_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Report Type" }, "topic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic" }, "topic_context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Topic Context" }, "total_prompts": { "type": "integer", "title": "Total Prompts", "default": 0 }, "model_used": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Used" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration Seconds" }, "visibility_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Score" }, "brand_mention_count": { "type": "integer", "title": "Brand Mention Count", "default": 0 }, "brand_mention_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Brand Mention Rate" }, "avg_brand_position": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Brand Position" }, "top_position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Top Position" }, "win_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Win Rate" }, "top_3_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top 3 Rate" }, "share_of_voice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Share Of Voice" }, "brand_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Brand Rank" }, "top_competitors": { "items": { "type": "string" }, "type": "array", "title": "Top Competitors" }, "market": { "additionalProperties": true, "type": "object", "title": "Market" } }, "type": "object", "required": [ "id", "brand_id", "created_at" ], "title": "ResearchRunListItem", "description": "Compact summary of a prompt_reports row." }, "ResearchRunsListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/ResearchRunListItem" }, "type": "array", "title": "Runs" }, "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "offset": { "type": "integer", "title": "Offset" } }, "type": "object", "required": [ "runs", "total", "limit", "offset" ], "title": "ResearchRunsListResponse" }, "ResearchSnapshotCreditsResponse": { "properties": { "used": { "type": "integer", "title": "Used" }, "limit": { "type": "integer", "title": "Limit" }, "remaining": { "type": "integer", "title": "Remaining" }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan" } }, "type": "object", "required": [ "used", "limit", "remaining" ], "title": "ResearchSnapshotCreditsResponse" }, "ResultPublicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "action_id": { "type": "string", "title": "Action Id" }, "verdict": { "type": "string", "title": "Verdict" }, "family": { "type": "string", "title": "Family" }, "summary": { "type": "string", "title": "Summary" }, "primary_metric": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Primary Metric" }, "window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Window Days" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "measured_at": { "type": "string", "title": "Measured At" }, "rolled_back": { "type": "boolean", "title": "Rolled Back", "default": false }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Url" } }, "type": "object", "required": [ "id", "action_id", "verdict", "family", "summary", "measured_at" ], "title": "ResultPublicItem", "description": "What a completed change did, measured by the pipeline.\n\n`verdict` is never a causal claim. `harm` renders as the honest sentence\nplus its metrics and nothing else (rule 4)." }, "ResultsResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/ResultPublicItem" }, "type": "array", "title": "Results" }, "meta": { "$ref": "#/components/schemas/UnityListMeta" }, "verdict_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Verdict Counts" } }, "type": "object", "required": [ "results", "meta", "verdict_counts" ], "title": "ResultsResponse" }, "RunSnapshotPublicRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "topic": { "type": "string", "maxLength": 200, "minLength": 2, "title": "Topic" }, "topic_context": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Topic Context" } }, "type": "object", "required": [ "brand_id", "topic" ], "title": "RunSnapshotPublicRequest" }, "RunSnapshotPublicResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "message": { "type": "string", "title": "Message" }, "placeholder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Placeholder Id" }, "remaining": { "type": "integer", "title": "Remaining" }, "limit": { "type": "integer", "title": "Limit" } }, "type": "object", "required": [ "success", "message", "remaining", "limit" ], "title": "RunSnapshotPublicResponse" }, "ScoresResponse": { "properties": { "brand": { "additionalProperties": true, "type": "object", "title": "Brand" }, "latest_scores": { "$ref": "#/components/schemas/LatestScores" }, "trend": { "$ref": "#/components/schemas/TrendInfo" }, "historical": { "items": { "$ref": "#/components/schemas/HistoricalPoint" }, "type": "array", "title": "Historical" }, "filters_applied": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Filters Applied" } }, "type": "object", "required": [ "brand", "latest_scores", "trend", "historical" ], "title": "ScoresResponse", "description": "GET /get-scores response." }, "SentimentDistribution": { "properties": { "positive": { "type": "integer", "title": "Positive", "default": 0 }, "neutral": { "type": "integer", "title": "Neutral", "default": 0 }, "negative": { "type": "integer", "title": "Negative", "default": 0 }, "mixed": { "type": "integer", "title": "Mixed", "default": 0 } }, "type": "object", "title": "SentimentDistribution" }, "SentimentTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sentiment" } }, "type": "object", "required": [ "date" ], "title": "SentimentTrendPoint" }, "SetConversionRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "event_name": { "type": "string", "title": "Event Name" }, "value_per_conversion": { "type": "number", "title": "Value Per Conversion" } }, "type": "object", "required": [ "brand_id", "event_name", "value_per_conversion" ], "title": "SetConversionRequest" }, "SourceTypeStats": { "properties": { "source_type": { "type": "string", "title": "Source Type" }, "count": { "type": "integer", "title": "Count" }, "percentage": { "type": "number", "title": "Percentage" } }, "type": "object", "required": [ "source_type", "count", "percentage" ], "title": "SourceTypeStats" }, "SuggestPromptsApiRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "focus": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Focus" }, "limit": { "type": "integer", "maximum": 10.0, "minimum": 1.0, "title": "Limit", "default": 8 }, "exclude_tracked": { "type": "boolean", "title": "Exclude Tracked", "default": true } }, "type": "object", "required": [ "brand_id" ], "title": "SuggestPromptsApiRequest", "description": "POST /get-prompts/suggest body." }, "SuggestPromptsApiResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "brand": { "type": "string", "title": "Brand" }, "focus": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus" }, "language": { "type": "string", "title": "Language" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "count": { "type": "integer", "title": "Count" }, "suggestions": { "items": { "type": "string" }, "type": "array", "title": "Suggestions" }, "excluded_as_tracked": { "type": "integer", "title": "Excluded As Tracked" }, "note": { "type": "string", "title": "Note" } }, "type": "object", "required": [ "brand_id", "brand", "language", "count", "suggestions", "excluded_as_tracked", "note" ], "title": "SuggestPromptsApiResponse" }, "TagItem": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Colour" } }, "type": "object", "required": [ "id", "name" ], "title": "TagItem", "description": "Tag in API response." }, "TagListItem": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Colour" }, "prompt_count": { "type": "integer", "title": "Prompt Count", "default": 0 } }, "type": "object", "required": [ "id", "name" ], "title": "TagListItem", "description": "Brand tag with its current prompt membership count." }, "TagsListResponse": { "properties": { "tags": { "items": { "$ref": "#/components/schemas/TagListItem" }, "type": "array", "title": "Tags" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "tags", "total" ], "title": "TagsListResponse", "description": "GET /get-tags response." }, "TopSpotOwnership": { "properties": { "prompt": { "type": "string", "title": "Prompt" }, "top_brand": { "type": "string", "title": "Top Brand" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "prompt", "top_brand", "count" ], "title": "TopSpotOwnership", "description": "Top spot ownership for a prompt." }, "TrafficConversionMutationResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "event_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Name" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Value" }, "deleted": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deleted" } }, "additionalProperties": true, "type": "object", "required": [ "success" ], "title": "TrafficConversionMutationResponse" }, "TrafficDeviceItem": { "properties": { "device": { "type": "string", "title": "Device" }, "sessions": { "type": "integer", "title": "Sessions" }, "percentage": { "type": "number", "title": "Percentage" } }, "type": "object", "required": [ "device", "sessions", "percentage" ], "title": "TrafficDeviceItem" }, "TrafficGeoItem": { "properties": { "country": { "type": "string", "title": "Country" }, "sessions": { "type": "integer", "title": "Sessions" } }, "type": "object", "required": [ "country", "sessions" ], "title": "TrafficGeoItem" }, "TrafficHourlyPoint": { "properties": { "hour": { "type": "integer", "title": "Hour" }, "count": { "type": "integer", "title": "Count" } }, "type": "object", "required": [ "hour", "count" ], "title": "TrafficHourlyPoint" }, "TrafficLandingPage": { "properties": { "page": { "type": "string", "title": "Page" }, "sessions": { "type": "integer", "title": "Sessions" }, "engagement_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Engagement Rate" } }, "type": "object", "required": [ "page", "sessions" ], "title": "TrafficLandingPage" }, "TrafficReportResponse": { "properties": { "ai_sessions": { "type": "integer", "title": "Ai Sessions" }, "total_sessions": { "type": "integer", "title": "Total Sessions" }, "ai_percentage": { "type": "number", "title": "Ai Percentage" }, "ai_engagement_rate": { "type": "number", "title": "Ai Engagement Rate" }, "ai_avg_duration": { "type": "number", "title": "Ai Avg Duration" }, "ai_sources": { "items": { "$ref": "#/components/schemas/TrafficSourceItem" }, "type": "array", "title": "Ai Sources" }, "trend_data": { "items": { "$ref": "#/components/schemas/TrafficTrendPoint" }, "type": "array", "title": "Trend Data" }, "top_landing_pages": { "items": { "$ref": "#/components/schemas/TrafficLandingPage" }, "type": "array", "title": "Top Landing Pages" }, "geo_data": { "items": { "$ref": "#/components/schemas/TrafficGeoItem" }, "type": "array", "title": "Geo Data" }, "device_data": { "items": { "$ref": "#/components/schemas/TrafficDeviceItem" }, "type": "array", "title": "Device Data" }, "cached_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cached At" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, "type": "object", "required": [ "ai_sessions", "total_sessions", "ai_percentage", "ai_engagement_rate", "ai_avg_duration", "ai_sources", "trend_data", "top_landing_pages", "geo_data", "device_data" ], "title": "TrafficReportResponse", "description": "GET /traffic/report" }, "TrafficSourceItem": { "properties": { "source": { "type": "string", "title": "Source" }, "sessions": { "type": "integer", "title": "Sessions" }, "percentage": { "type": "number", "title": "Percentage" } }, "type": "object", "required": [ "source", "sessions", "percentage" ], "title": "TrafficSourceItem" }, "TrafficStatusResponse": { "properties": { "connected": { "type": "boolean", "title": "Connected" }, "property_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Property Name" }, "last_refreshed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Refreshed" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } }, "type": "object", "required": [ "connected" ], "title": "TrafficStatusResponse", "description": "GET /traffic/status" }, "TrafficTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "ai_sessions": { "type": "integer", "title": "Ai Sessions" }, "total_sessions": { "type": "integer", "title": "Total Sessions" } }, "type": "object", "required": [ "date", "ai_sessions", "total_sessions" ], "title": "TrafficTrendPoint" }, "TrafficVisitorItem": { "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "landing_page": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Landing Page" }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "device": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Device" }, "pages_viewed": { "type": "integer", "title": "Pages Viewed", "default": 0 }, "duration_seconds": { "type": "number", "title": "Duration Seconds", "default": 0 } }, "type": "object", "title": "TrafficVisitorItem" }, "TrafficVisitorsResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/TrafficVisitorItem" }, "type": "array", "title": "Sessions" }, "total_today": { "type": "integer", "title": "Total Today" }, "last_hour": { "type": "integer", "title": "Last Hour" }, "hourly_data": { "items": { "$ref": "#/components/schemas/TrafficHourlyPoint" }, "type": "array", "title": "Hourly Data" } }, "type": "object", "required": [ "sessions", "total_today", "last_hour", "hourly_data" ], "title": "TrafficVisitorsResponse", "description": "GET /traffic/visitors" }, "TrendInfo": { "properties": { "visibility_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Visibility Change" }, "presence_change": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Presence Change" }, "period_days": { "type": "integer", "title": "Period Days" }, "reports_count": { "type": "integer", "title": "Reports Count", "default": 0 } }, "type": "object", "required": [ "period_days" ], "title": "TrendInfo", "description": "Trend information." }, "UnityListMeta": { "properties": { "total": { "type": "integer", "title": "Total" }, "limit": { "type": "integer", "title": "Limit" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "total", "limit" ], "title": "UnityListMeta", "description": "Cursor pagination (07 \u00a711 rule 6). Never mixed with PaginationInfo." }, "UpdateAliasesApiRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "aliases": { "items": { "type": "string" }, "type": "array", "title": "Aliases" } }, "type": "object", "required": [ "brand_id", "aliases" ], "title": "UpdateAliasesApiRequest", "description": "PUT /get-brands/aliases request body." }, "UpdateBrandLocationRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "country": { "type": "string", "title": "Country" }, "location_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Region" }, "location_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location City" }, "location_dataseo_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Location Dataseo Code" } }, "type": "object", "required": [ "brand_id", "country" ], "title": "UpdateBrandLocationRequest", "description": "PUT /get-brands/location request body." }, "UpdateBrandLocationResponse": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "location": { "type": "string", "title": "Location" }, "location_region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location Region" }, "location_city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location City" }, "location_dataseo_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Location Dataseo Code" }, "primary_market": { "anyOf": [ { "$ref": "#/components/schemas/MarketItem" }, { "type": "null" } ] } }, "type": "object", "required": [ "brand_id", "location" ], "title": "UpdateBrandLocationResponse", "description": "PUT /get-brands/location response." }, "UpdatePromptRequest": { "properties": { "prompt_id": { "type": "string", "title": "Prompt Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" }, "focus_area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Focus Area" }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intent" }, "audience": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audience" } }, "type": "object", "required": [ "prompt_id" ], "title": "UpdatePromptRequest", "description": "PUT /get-prompts request body." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VisibilityByModelItem": { "properties": { "model": { "type": "string", "title": "Model" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "trend": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trend" } }, "type": "object", "required": [ "model", "visibility", "presence" ], "title": "VisibilityByModelItem" }, "VisibilityByModelResponse": { "properties": { "brand": { "additionalProperties": true, "type": "object", "title": "Brand" }, "models": { "items": { "$ref": "#/components/schemas/VisibilityByModelItem" }, "type": "array", "title": "Models" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "brand", "models", "period_days" ], "title": "VisibilityByModelResponse", "description": "GET /get-scores?view=by_model" }, "VisibilityByPromptItem": { "properties": { "prompt_id": { "type": "string", "title": "Prompt Id" }, "prompt_text": { "type": "string", "title": "Prompt Text" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" } }, "type": "object", "required": [ "prompt_id", "prompt_text", "visibility", "presence" ], "title": "VisibilityByPromptItem" }, "VisibilityByPromptResponse": { "properties": { "brand": { "additionalProperties": true, "type": "object", "title": "Brand" }, "prompts": { "items": { "$ref": "#/components/schemas/VisibilityByPromptItem" }, "type": "array", "title": "Prompts" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "brand", "prompts", "period_days" ], "title": "VisibilityByPromptResponse", "description": "GET /get-scores?view=by_prompt" }, "VisibilityTimeSeriesPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "visibility": { "type": "number", "title": "Visibility" }, "presence": { "type": "number", "title": "Presence" }, "average_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Rank" }, "mentions": { "type": "integer", "title": "Mentions", "default": 0 }, "models_mentioned": { "type": "integer", "title": "Models Mentioned", "default": 0 } }, "type": "object", "required": [ "date", "visibility", "presence" ], "title": "VisibilityTimeSeriesPoint" }, "VisibilityTimeSeriesResponse": { "properties": { "brand": { "additionalProperties": true, "type": "object", "title": "Brand" }, "time_series": { "items": { "$ref": "#/components/schemas/VisibilityTimeSeriesPoint" }, "type": "array", "title": "Time Series" }, "period_days": { "type": "integer", "title": "Period Days" } }, "type": "object", "required": [ "brand", "time_series", "period_days" ], "title": "VisibilityTimeSeriesResponse", "description": "GET /get-scores?view=time_series" }, "WebhookCreateBody": { "properties": { "url": { "type": "string", "title": "Url", "description": "HTTPS endpoint URL" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events", "description": "Event types to subscribe to" }, "brand_id": { "type": "string", "title": "Brand Id", "description": "Brand UUID" }, "auth_type": { "anyOf": [ { "type": "string", "enum": [ "none", "bearer", "basic", "api_key" ] }, { "type": "null" } ], "title": "Auth Type", "description": "Authentication: \"none\", \"bearer\", \"basic\", or \"api_key\"", "default": "none" }, "auth_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Token", "description": "Bearer token (if auth_type is bearer)" }, "auth_username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Username" }, "auth_password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Auth Password" }, "api_key_header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Header" }, "api_key_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Value" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret", "description": "Custom signing secret (auto-generated if omitted)" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers" }, "payload_template": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload Template" } }, "type": "object", "required": [ "url", "events", "brand_id" ], "title": "WebhookCreateBody" }, "WebhookListResponse": { "properties": { "webhooks": { "items": { "$ref": "#/components/schemas/WebhookPublicResponse" }, "type": "array", "title": "Webhooks" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "webhooks", "total" ], "title": "WebhookListResponse" }, "WebhookPublicResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "object": { "type": "string", "title": "Object", "default": "webhook" }, "url": { "type": "string", "title": "Url" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "brand_id": { "type": "string", "title": "Brand Id" }, "provider": { "type": "string", "title": "Provider" }, "active": { "type": "boolean", "title": "Active" }, "signing_secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signing Secret" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "url", "events", "brand_id", "provider", "active", "created_at" ], "title": "WebhookPublicResponse" }, "WebhookTestResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Status Code" }, "response_time_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Time Ms" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "success" ], "title": "WebhookTestResponse" }, "WorkflowFromTemplateRequest": { "properties": { "brand_id": { "type": "string", "title": "Brand Id" }, "template_id": { "type": "string", "title": "Template Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name" } }, "type": "object", "required": [ "brand_id", "template_id" ], "title": "WorkflowFromTemplateRequest", "description": "POST /workflows/from-template body." }, "WorkflowPublicResponse": { "properties": { "workflows": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Workflows" }, "runs": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Runs" }, "run": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Run" }, "templates": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Templates" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" } }, "additionalProperties": true, "type": "object", "title": "WorkflowPublicResponse" }, "WorkflowStatusPatchRequest": { "properties": { "status": { "type": "string", "enum": [ "active", "paused", "deleted" ], "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "WorkflowStatusPatchRequest", "description": "PATCH /workflows/{id} body \u2014 only status changes supported." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.trakkr.ai", "description": "Production API" } ] }