{ "openapi": "3.1.0", "info": { "title": "GEO Platform — Public API", "version": "v1", "description": "Publiczne REST API GEO Platform. Uwierzytelnianie nagłówkiem `X-API-Key`. Base URL: `https://geoplatform.pl`. Zasada: wszystko, co pokazuje dashboard, wyciągniesz jako dane." }, "paths": { "/v1/visibility/summary": { "get": { "tags": [ "public-api" ], "summary": "AI visibility summary", "description": "Share of Voice, sentiment, position per platform for the last N days.", "operationId": "v1_visibility_summary_v1_visibility_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__api_v1__VisibilitySummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/visibility/checks": { "get": { "tags": [ "public-api" ], "summary": "Recent AI visibility checks", "description": "List of recent visibility check results (brand mentions, sentiment, position).", "operationId": "v1_visibility_checks_v1_visibility_checks_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by platform: chatgpt, perplexity, gemini, claude, google_aio", "title": "Platform" }, "description": "Filter by platform: chatgpt, perplexity, gemini, claude, google_aio" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityChecksResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/visibility/timeseries": { "get": { "tags": [ "public-api" ], "summary": "Daily Share of Voice trend", "description": "Daily Share of Voice (%) over generic questions, with a per-platform breakdown.", "operationId": "v1_visibility_timeseries_v1_visibility_timeseries_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityTimeseriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/visibility/questions": { "get": { "tags": [ "public-api" ], "summary": "Question SoV ranking", "description": "Per-question Share of Voice ranking over generic brand-map questions: top performers and gaps.", "operationId": "v1_visibility_questions_v1_visibility_questions_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "top_n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Top N" } }, { "name": "gap_n", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Gap N" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisibilityQuestionsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/topics": { "get": { "tags": [ "public-api" ], "summary": "Topic map", "description": "List of tracked questions from the topic map with AI gap status.", "operationId": "v1_topics_v1_topics_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status: approved, pending, etc.", "title": "Status" }, "description": "Filter by status: approved, pending, etc." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/content": { "get": { "tags": [ "public-api" ], "summary": "Published content list", "description": "List of GEO content pieces with scores and publication status.", "operationId": "v1_content_v1_content_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status: approved, published, draft", "title": "Status" }, "description": "Filter by status: approved, published, draft" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/bot-analytics/summary": { "get": { "tags": [ "public-api" ], "summary": "AI bot visit summary", "description": "Aggregate stats on AI crawler visits (GPTBot, ClaudeBot, PerplexityBot, etc.).", "operationId": "v1_bot_analytics_summary_v1_bot_analytics_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__api_v1__BotSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/bot-analytics/timeseries": { "get": { "tags": [ "public-api" ], "summary": "Daily AI bot visits", "description": "Daily AI crawler visit counts with a per-bot breakdown (GPTBot, ClaudeBot, PerplexityBot, etc.).", "operationId": "v1_bot_analytics_timeseries_v1_bot_analytics_timeseries_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotTimeseriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/traffic/summary": { "get": { "tags": [ "public-api" ], "summary": "AI traffic summary", "description": "Traffic from AI platforms (ChatGPT, Perplexity, etc.) via GA4 or Plausible.", "operationId": "v1_traffic_summary_v1_traffic_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__api_v1__TrafficSummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/traffic/timeseries": { "get": { "tags": [ "public-api" ], "summary": "Daily AI traffic", "description": "Per-day AI traffic records per source (sessions, users, pageviews).", "operationId": "v1_traffic_timeseries_v1_traffic_timeseries_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficTimeseriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/products": { "get": { "tags": [ "public-api" ], "summary": "Tracked product catalog", "description": "Cursor-paginated list of tracked products. Pass `meta.next_cursor` back as `?cursor=` for the next page.", "operationId": "v1_products_v1_products_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque pagination cursor from a previous response's meta.next_cursor", "title": "Cursor" }, "description": "Opaque pagination cursor from a previous response's meta.next_cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only products currently tracked (is_active=true)", "default": true, "title": "Active Only" }, "description": "Only products currently tracked (is_active=true)" }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/products/visibility/summary": { "get": { "tags": [ "public-api" ], "summary": "Product visibility summary", "description": "Catalog-level aggregate: mention rate (Share of Voice), price issues, hallucinations, per-product stats.", "operationId": "v1_products_visibility_summary_v1_products_visibility_summary_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductVisibilitySummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/products/share-of-shelf": { "get": { "tags": [ "public-api" ], "summary": "Share of Shelf", "description": "Share of Shelf in AI shopping answers — overall + per-category + per-platform, each with a period-over-period trend.", "operationId": "v1_products_share_of_shelf_v1_products_share_of_shelf_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one product category", "title": "Category" }, "description": "Restrict to one product category" }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareOfShelfResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/products/{product_id}/visibility": { "get": { "tags": [ "public-api" ], "summary": "Per-SKU visibility", "description": "Per-SKU daily visibility trend (position/competitors, attributed from category buyer-queries) plus price-accuracy history.", "operationId": "v1_product_visibility_v1_products__product_id__visibility_get", "parameters": [ { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuVisibilityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/attribution/revenue": { "get": { "tags": [ "public-api" ], "summary": "Revenue attributed to AI", "description": "Net revenue grouped per category or per SKU, with the AI proof ladder (hard / self-reported / probable) reported separately — never summed.", "operationId": "v1_attribution_revenue_v1_attribution_revenue_get", "parameters": [ { "name": "group", "in": "query", "required": false, "schema": { "type": "string", "description": "Grouping dimension: category | sku", "default": "category", "title": "Group" }, "description": "Grouping dimension: category | sku" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenueBreakdownResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/attribution/roi": { "get": { "tags": [ "public-api" ], "summary": "AI channel ROI", "description": "ROI of the AI channel: cost (subscription + content + opt-in AI usage) vs hard and estimated revenue, reported separately (§2).", "operationId": "v1_attribution_roi_v1_attribution_roi_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__api_v1__RoiResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/attribution/timeseries": { "get": { "tags": [ "public-api" ], "summary": "Daily attribution trend", "description": "Daily sessions and AI-sourced sessions from the attribution pixel.", "operationId": "v1_attribution_timeseries_v1_attribution_timeseries_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionTimeseriesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/brand-safety/hallucinations": { "get": { "tags": [ "public-api" ], "summary": "Detected hallucinations", "description": "List of AI hallucination checks about the brand, with severity and takedown status.", "operationId": "v1_brand_safety_hallucinations_v1_brand_safety_hallucinations_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "hallucinations_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only rows flagged as hallucinations", "default": true, "title": "Hallucinations Only" }, "description": "Only rows flagged as hallucinations" }, { "name": "severity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by severity: critical, high, medium, low", "title": "Severity" }, "description": "Filter by severity: critical, high, medium, low" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HallucinationListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/brand-safety/summary": { "get": { "tags": [ "public-api" ], "summary": "Brand safety summary", "description": "Aggregate: hallucination rate, breakdown by severity and platform, unresolved critical count.", "operationId": "v1_brand_safety_summary_v1_brand_safety_summary_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__schemas__api_v1__BrandSafetySummaryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders": { "post": { "tags": [ "public-api" ], "summary": "Upsert one order", "description": "Canonical order ingest. Idempotent upsert by external_id (source_platform='api'); send the same external_id again to update status (e.g. returns/cancellations). Requires scope orders:write.", "operationId": "v1_order_upsert_v1_orders_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpsertResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "public-api" ], "summary": "List synced orders", "description": "Minimal list for integration debugging (no line items). Requires scope orders:read.", "operationId": "v1_orders_list_v1_orders_get", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Only orders with ordered_at >= since (ISO 8601)", "title": "Since" }, "description": "Only orders with ordered_at >= since (ISO 8601)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by status: placed, paid, shipped, completed, cancelled, returned", "title": "Status" }, "description": "Filter by status: placed, paid, shipped, completed, cancelled, returned" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersV1ListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders/batch": { "post": { "tags": [ "public-api" ], "summary": "Upsert a batch of orders", "description": "Up to 500 orders per request. Partial successes — failed orders land in `errors` with their index.", "operationId": "v1_orders_batch_v1_orders_batch_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBatchIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBatchResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ApiMeta": { "properties": { "generated_at": { "type": "string", "format": "date-time", "title": "Generated At" }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Period Days" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group" } }, "type": "object", "required": [ "generated_at" ], "title": "ApiMeta", "description": "Envelope metadata. `next_cursor` is present only on cursor-paginated lists;\n`group` echoes the grouping dimension on the revenue-breakdown endpoint." }, "AttributionTimeseriesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AttributionTrendPoint" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "AttributionTimeseriesResponse" }, "AttributionTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "sessions": { "type": "integer", "title": "Sessions" }, "ai_sessions": { "type": "integer", "title": "Ai Sessions" } }, "type": "object", "required": [ "date", "sessions", "ai_sessions" ], "title": "AttributionTrendPoint" }, "BotTimeseriesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BotTrendPoint" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "BotTimeseriesResponse" }, "BotTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "total": { "type": "integer", "title": "Total" }, "by_bot": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Bot" } }, "type": "object", "required": [ "date", "total", "by_bot" ], "title": "BotTrendPoint" }, "BrandSafetySummary": { "properties": { "total_checks": { "type": "integer", "title": "Total Checks" }, "total_hallucinations": { "type": "integer", "title": "Total Hallucinations" }, "hallucination_rate": { "type": "number", "title": "Hallucination Rate" }, "by_severity": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Severity" }, "by_platform": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "By Platform" }, "facts_count": { "type": "integer", "title": "Facts Count" }, "critical_unresolved": { "type": "integer", "title": "Critical Unresolved" } }, "type": "object", "required": [ "total_checks", "total_hallucinations", "hallucination_rate", "by_severity", "by_platform", "facts_count", "critical_unresolved" ], "title": "BrandSafetySummary" }, "ContentItem": { "properties": { "id": { "type": "string", "title": "Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "format_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Format Type" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "geo_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Geo Score" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "refresh_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Refresh Score" }, "wp_post_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Wp Post Url" }, "webflow_item_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webflow Item Url" }, "ai_citations_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ai Citations Count" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "title", "format_type", "language", "geo_score", "status", "refresh_score", "wp_post_url", "webflow_item_url", "ai_citations_count", "created_at", "updated_at" ], "title": "ContentItem" }, "ContentListResponse": { "properties": { "content": { "items": { "$ref": "#/components/schemas/ContentItem" }, "type": "array", "title": "Content" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "content", "total" ], "title": "ContentListResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HallucinationListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/HallucinationOut" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "HallucinationListResponse" }, "HallucinationOut": { "properties": { "id": { "type": "string", "title": "Id" }, "checked_at": { "type": "string", "format": "date-time", "title": "Checked At" }, "platform": { "type": "string", "title": "Platform" }, "query": { "type": "string", "title": "Query" }, "ai_response_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Response Excerpt" }, "is_hallucination": { "type": "boolean", "title": "Is Hallucination" }, "hallucination_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hallucination Type" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" }, "suggested_action": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suggested Action" }, "takedown_status": { "type": "string", "title": "Takedown Status" } }, "type": "object", "required": [ "id", "checked_at", "platform", "query", "ai_response_excerpt", "is_hallucination", "hallucination_type", "severity", "suggested_action", "takedown_status" ], "title": "HallucinationOut" }, "OrderBatchError": { "properties": { "index": { "type": "integer", "title": "Index" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id" }, "error": { "type": "string", "title": "Error" } }, "type": "object", "required": [ "index", "external_id", "error" ], "title": "OrderBatchError" }, "OrderBatchIn": { "properties": { "orders": { "items": { "$ref": "#/components/schemas/OrderIn" }, "type": "array", "maxItems": 500, "minItems": 1, "title": "Orders" } }, "type": "object", "required": [ "orders" ], "title": "OrderBatchIn" }, "OrderBatchResult": { "properties": { "total": { "type": "integer", "title": "Total" }, "created": { "type": "integer", "title": "Created" }, "updated": { "type": "integer", "title": "Updated" }, "failed": { "type": "integer", "title": "Failed" }, "results": { "items": { "$ref": "#/components/schemas/OrderUpsertResult" }, "type": "array", "title": "Results" }, "errors": { "items": { "$ref": "#/components/schemas/OrderBatchError" }, "type": "array", "title": "Errors" } }, "type": "object", "required": [ "total", "created", "updated", "failed", "results", "errors" ], "title": "OrderBatchResult" }, "OrderIn": { "properties": { "external_id": { "type": "string", "maxLength": 100, "minLength": 1, "title": "External Id" }, "ordered_at": { "type": "string", "format": "date-time", "title": "Ordered At" }, "status": { "type": "string", "enum": [ "placed", "paid", "shipped", "completed", "cancelled", "returned" ], "title": "Status", "default": "placed" }, "total_value": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string" }, { "type": "null" } ], "title": "Total Value" }, "currency": { "type": "string", "title": "Currency", "default": "PLN" }, "utm_source": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Utm Source" }, "utm_medium": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Utm Medium" }, "utm_campaign": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Utm Campaign" }, "utm_content": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Utm Content" }, "items": { "items": { "$ref": "#/components/schemas/OrderItemIn" }, "type": "array", "maxItems": 200, "title": "Items" } }, "type": "object", "required": [ "external_id", "ordered_at" ], "title": "OrderIn", "examples": [ { "currency": "PLN", "external_id": "ORD-2026-0042", "items": [ { "name": "Widget Pro", "product_external_id": "SKU-123", "quantity": 1, "total_price": "199.90", "unit_price": "199.90" }, { "name": "Dostawa", "product_external_id": "SKU-999", "quantity": 1, "total_price": "50.00", "unit_price": "50.00" } ], "ordered_at": "2026-07-19T10:30:00Z", "status": "paid", "total_value": "249.90", "utm_medium": "ai_referral", "utm_source": "chatgpt" } ] }, "OrderItemIn": { "properties": { "product_external_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Product External Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Name" }, "quantity": { "type": "integer", "minimum": 1.0, "title": "Quantity", "default": 1 }, "unit_price": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string" }, { "type": "null" } ], "title": "Unit Price" }, "total_price": { "anyOf": [ { "type": "number", "minimum": 0.0 }, { "type": "string" }, { "type": "null" } ], "title": "Total Price" } }, "type": "object", "title": "OrderItemIn" }, "OrderListItem": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "type": "string", "title": "External Id" }, "source_platform": { "type": "string", "title": "Source Platform" }, "ordered_at": { "type": "string", "title": "Ordered At" }, "status": { "type": "string", "title": "Status" }, "total_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Value" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "items_count": { "type": "integer", "title": "Items Count" }, "synced_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Synced At" } }, "type": "object", "required": [ "id", "external_id", "source_platform", "ordered_at", "status", "total_value", "currency", "items_count", "synced_at" ], "title": "OrderListItem" }, "OrderUpsertResult": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "type": "string", "title": "External Id" }, "action": { "type": "string", "enum": [ "created", "updated" ], "title": "Action" }, "items_total": { "type": "integer", "title": "Items Total" }, "items_matched": { "type": "integer", "title": "Items Matched" } }, "type": "object", "required": [ "id", "external_id", "action", "items_total", "items_matched" ], "title": "OrderUpsertResult" }, "OrdersV1ListResponse": { "properties": { "orders": { "items": { "$ref": "#/components/schemas/OrderListItem" }, "type": "array", "title": "Orders" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "orders", "total" ], "title": "OrdersV1ListResponse" }, "PriceAccuracy": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "current_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Current Price" }, "currency": { "type": "string", "title": "Currency" }, "accuracy_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Accuracy Rate" }, "points": { "items": { "$ref": "#/components/schemas/PriceAccuracyPoint" }, "type": "array", "title": "Points" } }, "type": "object", "required": [ "product_id", "current_price", "currency", "accuracy_rate", "points" ], "title": "PriceAccuracy" }, "PriceAccuracyPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "platform": { "type": "string", "title": "Platform" }, "real_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Real Price" }, "ai_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Ai Price" }, "correct": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Correct" }, "delta_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Delta Pct" } }, "type": "object", "required": [ "date", "platform", "real_price", "ai_price", "correct", "delta_pct" ], "title": "PriceAccuracyPoint" }, "ProductListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductOut" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "ProductListResponse" }, "ProductOut": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id" }, "source_platform": { "type": "string", "title": "Source Platform" }, "name": { "type": "string", "title": "Name" }, "category_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category Path" }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand" }, "price_current": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Price Current" }, "price_currency": { "type": "string", "title": "Price Currency" }, "stock_status": { "type": "string", "title": "Stock Status" }, "product_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Url" }, "is_active": { "type": "boolean", "title": "Is Active" }, "is_priority": { "type": "boolean", "title": "Is Priority" } }, "type": "object", "required": [ "id", "external_id", "source_platform", "name", "category_path", "brand", "price_current", "price_currency", "stock_status", "product_url", "is_active", "is_priority" ], "title": "ProductOut" }, "ProductStat": { "properties": { "name": { "type": "string", "title": "Name" }, "total_checks": { "type": "integer", "title": "Total Checks" }, "mention_rate": { "type": "number", "title": "Mention Rate" }, "price_issues": { "type": "integer", "title": "Price Issues" } }, "type": "object", "required": [ "name", "total_checks", "mention_rate", "price_issues" ], "title": "ProductStat" }, "ProductVisibilitySummary": { "properties": { "total_products": { "type": "integer", "title": "Total Products" }, "total_checks": { "type": "integer", "title": "Total Checks" }, "mention_rate": { "type": "number", "title": "Mention Rate" }, "price_issues": { "type": "integer", "title": "Price Issues" }, "hallucination_count": { "type": "integer", "title": "Hallucination Count" }, "product_stats": { "items": { "$ref": "#/components/schemas/ProductStat" }, "type": "array", "title": "Product Stats" } }, "type": "object", "required": [ "total_products", "total_checks", "mention_rate", "price_issues", "hallucination_count", "product_stats" ], "title": "ProductVisibilitySummary" }, "ProductVisibilitySummaryResponse": { "properties": { "data": { "$ref": "#/components/schemas/ProductVisibilitySummary" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "ProductVisibilitySummaryResponse" }, "QuestionRankRow": { "properties": { "question": { "type": "string", "title": "Question" }, "checks": { "type": "integer", "title": "Checks" }, "sov_pct": { "type": "number", "title": "Sov Pct" } }, "type": "object", "required": [ "question", "checks", "sov_pct" ], "title": "QuestionRankRow" }, "QuestionRanking": { "properties": { "top": { "items": { "$ref": "#/components/schemas/QuestionRankRow" }, "type": "array", "title": "Top" }, "gaps": { "items": { "$ref": "#/components/schemas/QuestionRankRow" }, "type": "array", "title": "Gaps" } }, "type": "object", "required": [ "top", "gaps" ], "title": "QuestionRanking" }, "RevenueBreakdownResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/RevenueRow" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "RevenueBreakdownResponse" }, "RevenueRow": { "properties": { "key": { "type": "string", "title": "Key" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "orders_count": { "type": "integer", "title": "Orders Count" }, "quantity": { "type": "integer", "title": "Quantity" }, "revenue_by_currency": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Revenue By Currency" }, "ai_hard_orders": { "type": "integer", "title": "Ai Hard Orders" }, "ai_hard_revenue_by_currency": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Ai Hard Revenue By Currency" }, "ai_self_reported_orders": { "type": "integer", "title": "Ai Self Reported Orders" }, "ai_self_reported_revenue_by_currency": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Ai Self Reported Revenue By Currency" }, "ai_probable_orders": { "type": "integer", "title": "Ai Probable Orders" }, "ai_probable_revenue_by_currency": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Ai Probable Revenue By Currency" }, "product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "required": [ "key", "label", "orders_count", "quantity", "revenue_by_currency", "ai_hard_orders", "ai_hard_revenue_by_currency", "ai_self_reported_orders", "ai_self_reported_revenue_by_currency", "ai_probable_orders", "ai_probable_revenue_by_currency" ], "title": "RevenueRow" }, "ShareOfShelfResponse": { "properties": { "data": { "type": "object", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "ShareOfShelfResponse", "description": "Catalog Share of Shelf — overall + per-category + per-platform, each with a\nperiod-over-period trend delta. Rich nested blocks kept as-is." }, "SkuVisibilityData": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "visibility": { "type": "object", "title": "Visibility" }, "price_accuracy": { "$ref": "#/components/schemas/PriceAccuracy" } }, "type": "object", "required": [ "product_id", "visibility", "price_accuracy" ], "title": "SkuVisibilityData", "description": "Per-SKU visibility (position/competitors, attributed from category buyer-queries)\nplus price-accuracy history. The `visibility` block mirrors\nproduct_attribution_service.get_sku_visibility_multi (rich, nested)." }, "SkuVisibilityResponse": { "properties": { "data": { "$ref": "#/components/schemas/SkuVisibilityData" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "SkuVisibilityResponse" }, "TopicItem": { "properties": { "id": { "type": "string", "title": "Id" }, "question": { "type": "string", "title": "Question" }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "has_ai_gap": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Has Ai Gap" }, "recommended_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recommended Format" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "question", "stage", "status", "language", "has_ai_gap", "recommended_format", "created_at" ], "title": "TopicItem" }, "TopicsResponse": { "properties": { "topics": { "items": { "$ref": "#/components/schemas/TopicItem" }, "type": "array", "title": "Topics" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "topics", "total" ], "title": "TopicsResponse" }, "TrafficTimeseriesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TrafficTrendPoint" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "TrafficTimeseriesResponse" }, "TrafficTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "source": { "type": "string", "title": "Source" }, "sessions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sessions" }, "users": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Users" }, "pageviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pageviews" }, "avg_duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Duration Seconds" } }, "type": "object", "required": [ "date", "source", "sessions", "users", "pageviews", "avg_duration_seconds" ], "title": "TrafficTrendPoint" }, "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" }, "VisibilityCheckItem": { "properties": { "id": { "type": "string", "title": "Id" }, "checked_at": { "type": "string", "title": "Checked At" }, "platform": { "type": "string", "title": "Platform" }, "question": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Question" }, "brand_mentioned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Brand Mentioned" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment" }, "sentiment_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sentiment Score" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Position" }, "response_excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response Excerpt" }, "competitors_mentioned": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Competitors Mentioned" } }, "type": "object", "required": [ "id", "checked_at", "platform", "question", "brand_mentioned", "sentiment", "sentiment_score", "position", "response_excerpt", "competitors_mentioned" ], "title": "VisibilityCheckItem" }, "VisibilityChecksResponse": { "properties": { "checks": { "items": { "$ref": "#/components/schemas/VisibilityCheckItem" }, "type": "array", "title": "Checks" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "checks", "total" ], "title": "VisibilityChecksResponse" }, "VisibilityQuestionsResponse": { "properties": { "data": { "$ref": "#/components/schemas/QuestionRanking" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "VisibilityQuestionsResponse" }, "VisibilityTimeseriesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/VisibilityTrendPoint" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "VisibilityTimeseriesResponse" }, "VisibilityTrendPoint": { "properties": { "date": { "type": "string", "title": "Date" }, "sov_pct": { "type": "number", "title": "Sov Pct" }, "by_platform": { "additionalProperties": { "type": "number" }, "type": "object", "title": "By Platform" } }, "type": "object", "required": [ "date", "sov_pct", "by_platform" ], "title": "VisibilityTrendPoint" }, "app__schemas__api_v1__BotSummaryResponse": { "properties": { "total_visits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Visits" }, "unique_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Unique Pages" }, "top_bot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Top Bot" }, "by_bot": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "By Bot" }, "period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Period Days" }, "cloudflare_configured": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cloudflare Configured" }, "month_visits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Month Visits" }, "month_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Month Limit" }, "limit_exceeded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Limit Exceeded" } }, "additionalProperties": true, "type": "object", "title": "BotSummaryResponse" }, "app__schemas__api_v1__BrandSafetySummaryResponse": { "properties": { "data": { "$ref": "#/components/schemas/BrandSafetySummary" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "BrandSafetySummaryResponse" }, "app__schemas__api_v1__RoiResponse": { "properties": { "data": { "type": "object", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "RoiResponse", "description": "ROI of the AI channel: cost vs revenue with the hard/estimated proof ladder\nreported separately (§2 — never merged). Rich nested blocks kept as-is." }, "app__schemas__api_v1__TrafficSummaryResponse": { "properties": { "period_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Period Days" }, "total_sessions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Sessions" }, "total_users": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Users" }, "total_pageviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pageviews" }, "top_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Top Source" }, "by_source": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "By Source" }, "trend": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Trend" }, "engagement": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Engagement" }, "diversity": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Diversity" }, "daily": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Daily" }, "top_pages": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Top Pages" } }, "additionalProperties": true, "type": "object", "title": "TrafficSummaryResponse" }, "app__schemas__api_v1__VisibilitySummaryResponse": { "properties": { "total_checks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Checks" }, "sov_eligible_checks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sov Eligible Checks" }, "brand_mentioned_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Brand Mentioned Count" }, "share_of_voice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Share Of Voice" }, "avg_sentiment_score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sentiment Score" }, "avg_position": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Position" }, "by_platform": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "By Platform" }, "sentiment_distribution": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Sentiment Distribution" }, "tone_distribution": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Tone Distribution" }, "competitors_frequency": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "object" }, { "type": "null" } ], "title": "Competitors Frequency" } }, "additionalProperties": true, "type": "object", "title": "VisibilitySummaryResponse" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Klucz API workspace'u. Utwórz go w panelu (sekcja Klucze API)." } } }, "tags": [ { "name": "auth", "description": "Logowanie, refresh tokenu, zmiana hasła" }, { "name": "admin", "description": "Superadmin: zarządzanie tenantami i użytkownikami" }, { "name": "profile", "description": "Profil firmy (nazwa, branża, lokalizacja, integracje CMS)" }, { "name": "onboarding", "description": "Wizard onboardingowy: crawl check, starter questions" }, { "name": "topics", "description": "Mapa tematyczna: generowanie pytań przez AI, CRUD, status" }, { "name": "content", "description": "Generowanie treści (artykuł/listicle/porównanie/FAQ), GEO score, workflow zatwierdzania" }, { "name": "distribution", "description": "Publikacja do WordPress / Webflow, eksport HTML/Markdown/JSON-LD, adaptacje" }, { "name": "audit", "description": "Audyt istniejących stron: crawl → GEO score → sugestie → poprawa AI" }, { "name": "reviews", "description": "Tracker recenzji (Google, Tripadvisor) + generator odpowiedzi AI" }, { "name": "visibility", "description": "AI Visibility Monitor: sprawdzanie 5 platform AI, SoV, sentyment, pozycja" }, { "name": "sources", "description": "Klasyfikacja cytowanych źródeł, luki źródłowe (Source Gap Analysis)" }, { "name": "crawl", "description": "Crawl Access Monitor: robots.txt, schema.org, sitemap — dostęp AI botów" }, { "name": "traffic", "description": "AI Traffic Monitor: ruch z ChatGPT/Perplexity/Gemini przez GA4 lub Plausible" }, { "name": "dashboard", "description": "Dashboard główny — KPI: widoczność, ruch, treści, crawl, source gaps" }, { "name": "reports", "description": "Raporty miesięczne PDF + tygodniowe podsumowanie email" }, { "name": "refresh", "description": "Content Refresh Engine: Refresh Score, lista przestarzałych treści, diff AI" }, { "name": "benchmark", "description": "Roczne raporty + benchmarki branżowe (anonimowe agregaty)" }, { "name": "personas", "description": "Persona tracking: definicje person buyer + persona-based visibility monitoring" }, { "name": "brand-safety", "description": "Brand Safety: zarządzanie faktami o firmie, wykrywanie halucynacji AI" }, { "name": "products", "description": "Product Visibility Tracker: katalog produktów e-commerce, widoczność w AI" }, { "name": "cost-center", "description": "Centrum Kosztów: wykorzystanie API, budżet miesięczny, eksport CSV" }, { "name": "health", "description": "Health check" }, { "name": "api-keys", "description": "Zarządzanie kluczami API: tworzenie, lista, odwoływanie (JWT auth)" }, { "name": "public-api", "description": "Public REST API v1: odczyt danych przez X-API-Key (rate-limited per tier)" } ], "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "url": "https://geoplatform.pl", "description": "Produkcja" } ] }