{ "openapi": "3.1.0", "info": { "title": "Skoup API", "version": "v1", "description": "Skoup public API \u2014 measure, fix and monetize your products' presence in AI answers." }, "servers": [ { "url": "https://api.skoup.ai/v1", "description": "Live and test" } ], "security": [ { "http": [] } ], "paths": { "/brands/{brand}/alerts": { "get": { "operationId": "public.alerts.index", "description": "Incidents detected at the end of the samplings \u2014 price\nhallucinations, wrong availability, visibility drops, new\ncompetitors, invented specs \u2014 newest first.", "summary": "List alerts", "tags": [ "Alerts" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "market", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicAlertResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAlertResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/alerts/{alert}": { "get": { "operationId": "public.alerts.show", "summary": "Retrieve an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "alert", "in": "path", "required": true, "description": "Alert id (`alrt_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicAlertResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAlertResource" } } } } } } }, "/brands/{brand}/alerts/{alert}/treat": { "post": { "operationId": "public.alerts.treat", "description": "Marks the alert as treated \u2014 the fix was made. Verify it next to\nclose it for good.", "summary": "Treat an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "alert", "in": "path", "required": true, "description": "Alert id (`alrt_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicAlertResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAlertResource" } } } } } } }, "/brands/{brand}/alerts/{alert}/dismiss": { "post": { "operationId": "public.alerts.dismiss", "description": "Ignores the alert. If the incident happens again, a new alert opens.", "summary": "Dismiss an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "alert", "in": "path", "required": true, "description": "Alert id (`alrt_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicAlertResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAlertResource" } } } } } } }, "/brands/{brand}/alerts/{alert}/verify": { "post": { "operationId": "public.alerts.verify", "description": "Re-samples the alert's query on every model to check the fix. The\nalert must be `treated`. Answers 202 when a verification starts, 200\nwhen one already in flight is reused; the verdict arrives later as\n`alert.resolved` (or `alert.updated` with `persisted: true`).\nRe-samplings are capped per brand and per day \u2014 see the\n`Skoup-Quota-Verifications` header.", "summary": "Verify an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "alert", "in": "path", "required": true, "description": "Alert id (`alrt_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brands": { "get": { "operationId": "public.brands.index", "description": "The brands of the workspace this key can reach \u2014 all of them, or the\nselection made when the key was created. Test keys see the sandbox brands.", "summary": "List brands", "tags": [ "Brands" ], "responses": { "200": { "description": "Array of `PublicBrandResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBrandResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}": { "get": { "operationId": "public.brands.show", "summary": "Retrieve a brand", "tags": [ "Brands" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicBrandResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBrandResource" } } } } } } }, "/brands/{brand}/competitors": { "get": { "operationId": "public.competitors.index", "description": "The competitor brands tracked on a market, with the share of the\nmarket's AI answers citing each over the period \u2014 the figures of the\nCompetitors screen, every model included.", "summary": "List tracked competitors", "tags": [ "Competitors" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicCompetitorResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicCompetitorResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/source-gaps": { "get": { "operationId": "public.source-gaps.index", "description": "The third-party sites (media, forums, resellers, videos) the AI\nassistants cite in answers that name a competitor and not the brand \u2014\nthe pages where a mention, a review or a listing would put the brand\nin the answers. Most cited without the brand first, every model included.", "summary": "List sources to win", "tags": [ "Competitors", "SourceGaps" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicSourceGapResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicSourceGapResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/events": { "get": { "operationId": "public.events.index", "description": "Events of the last 30 days, newest first \u2014 the same objects your\nwebhook endpoints receive. Use it to catch up after downtime.", "summary": "List events", "tags": [ "Events" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicEventResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicEventResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/events/{event}": { "get": { "operationId": "public.events.show", "summary": "Retrieve an event", "tags": [ "Events" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "Event id (`evt_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicEventResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEventResource" } } } } } } }, "/brands/{brand}/markets": { "get": { "operationId": "public.markets.index", "description": "The country markets of a brand. Measurements are per market: pass a\nmarket `code` (e.g. `FR`) to the endpoints that take a `market`.", "summary": "List markets", "tags": [ "Markets" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicMarketResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicMarketResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/locations": { "get": { "operationId": "public.locations.index", "description": "The establishments of a local brand (a chain of practices, stores or\nagencies is one brand with many establishments). Empty for a brand\nthat sells online. Queries, mentions and wrong-address alerts point\nat the establishment they are about.", "summary": "List establishments", "tags": [ "Markets", "Locations" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "market", "in": "query", "schema": { "type": "string" } }, { "name": "tracked", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Array of `PublicLocationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicLocationResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/metrics": { "get": { "operationId": "public.metrics.show", "description": "The headline numbers of a brand on a market over a period \u2014 the same\nfigures as the app's screens: share of the AI answers citing the brand\n(share of shelf) with its 95 % interval and week-over-week change,\naccuracy of the price and availability claims, AI readiness score and\nperception score. A block never measured is `null`, never zeros.", "summary": "Retrieve brand metrics", "tags": [ "Metrics" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicBrandMetricsResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBrandMetricsResource" } } } } } } }, "/brands/{brand}/products": { "get": { "operationId": "public.products.index", "description": "The brand's catalogue, newest first, variants included.", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicProductResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicProductResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } }, "post": { "operationId": "public.products.store", "description": "Adds a `manual` product \u2014 for stores without a connector. Its vendor\ndefaults to the brand name.", "summary": "Create a product", "tags": [ "Products" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductRequest" } } } }, "responses": { "201": { "description": "`PublicProductResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/products/{product}": { "get": { "operationId": "public.products.show", "summary": "Retrieve a product", "tags": [ "Products" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "product", "in": "path", "required": true, "description": "Product id (`prod_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicProductResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductResource" } } } } } }, "patch": { "operationId": "public.products.update", "description": "Only `manual` products can be updated: a synced product is read-only\n(`resource_read_only`) \u2014 fix it in the store, the next sync brings it.", "summary": "Update a product", "tags": [ "Products" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "product", "in": "path", "required": true, "description": "Product id (`prod_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductRequest" } } } }, "responses": { "200": { "description": "`PublicProductResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/products/{product}/write_backs": { "get": { "operationId": "public.products.write_backs", "description": "What Skoup wrote in the store for this product (copy, SEO fields,\nvariant barcodes), field by field with the value it replaced, newest\nfirst. Failed attempts are listed too, with their error.", "summary": "List a product's write-backs", "tags": [ "Products", "WriteBacks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "product", "in": "path", "required": true, "description": "Product id (`prod_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicWriteBackResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWriteBackResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/products/{product}/perception": { "get": { "operationId": "public.products.perception", "description": "How AI answers restitute the product's identity sheet on a market over\na period: verdict counts and score, then each differentiating attribute\n(USP) with the share of answers citing it and where to write it when\nit does not land. `sheet_version` is null for a product without an\nidentity sheet \u2014 nothing is judged without one.", "summary": "Retrieve a product's perception", "tags": [ "Products", "ProductPerception" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "product", "in": "path", "required": true, "description": "Product id (`prod_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicProductPerceptionResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProductPerceptionResource" } } } } } } }, "/brands/{brand}/queries": { "get": { "operationId": "public.queries.index", "description": "The queries of the brand's panel \u2014 the questions asked to the AI\nmodels every week \u2014 with the share of the answers citing the brand\nover the period.", "summary": "List queries", "tags": [ "Queries" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "market", "in": "query", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicQueryResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicQueryResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } }, "post": { "operationId": "public.queries.store", "description": "Adds a query to the panel of an activated market, enabled: it is\nasked from the next weekly sampling on. A duplicate on the market, or\na full quota (`quota_exceeded`), answers 422.", "summary": "Create a query", "tags": [ "Queries" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStoreQueryRequest" } } } }, "responses": { "201": { "description": "`PublicQueryResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/queries/{query}": { "get": { "operationId": "public.queries.show", "summary": "Retrieve a query", "tags": [ "Queries" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "query", "in": "path", "required": true, "description": "Query id (`qry_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicQueryResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryResource" } } } } } }, "patch": { "operationId": "public.queries.update", "description": "Edits the text or the category, or enables / disables the query.\nDisabling frees a slot of the quota; enabling takes one.", "summary": "Update a query", "tags": [ "Queries" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "query", "in": "path", "required": true, "description": "Query id (`qry_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpdateQueryRequest" } } } }, "responses": { "200": { "description": "`PublicQueryResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/readiness": { "get": { "operationId": "public.readiness.show", "description": "The latest AI readiness audit of a market \u2014 crawlability by AI bots,\nstructured data, product feed conformity, agentic checkout \u2014 scored\n/100 with its checks. 404 until a first audit ran on the market.", "summary": "Retrieve the readiness score", "tags": [ "Readiness" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicReadinessScoreResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReadinessScoreResource" } } } } } } }, "/brands/{brand}/attribution": { "get": { "operationId": "public.revenue.attribution", "description": "Orders and revenue attributed to AI surfaces (ChatGPT, Claude, Gemini,\nPerplexity\u2026) vs the whole store on a market over a period, by surface\nand by product \u2014 the figures of the Revenue screen. Attribution is\nlast-touch, read from the store's orders (referrer, `utm_source`,\n`ref`). Totals are `null` before the first order.", "summary": "Retrieve the AI attribution", "tags": [ "Revenue" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicAttributionResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAttributionResource" } } } } } } }, "/brands/{brand}/orders": { "get": { "operationId": "public.revenue.orders", "description": "The store orders attributed to an AI surface, newest first. Test\norders are excluded; no customer data is ever returned.", "summary": "List AI-attributed orders", "tags": [ "Revenue" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "surface", "in": "query", "schema": { "type": "string" } }, { "name": "country", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicOrderResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOrderResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/correlation": { "get": { "operationId": "public.revenue.correlation", "description": "AI visibility and AI-attributed revenue side by side, week by week,\nwith the fixes published each week \u2014 for the whole brand or one\ncatalogue category. Visibility is given raw per model (`hits` /\n`runs`) plus the all-models `share`. `weeks` is empty until the store\nsent a first order.", "summary": "Retrieve the visibility \u2194 revenue correlation", "tags": [ "Revenue" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicCorrelationResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCorrelationResource" } } } } } } }, "/brands/{brand}/subscriptions": { "get": { "operationId": "public.revenue.subscriptions", "description": "New subscriptions and new MRR of a SaaS brand on a market over a\nperiod, read from its Stripe, and the part the AI assistants brought\n\u2014 as the brand records it in the customer's or the subscription's\nmetadata (`referrer`, `utm_source`, `landing_url`). With the Growth\nplan or above, `weeks` puts the weekly AI visibility (raw counts per\nmodel) next to the new MRR. The blocks are `null` until Stripe is\nconnected and synced; SaaS brands only.", "summary": "Retrieve the AI subscriptions", "tags": [ "Revenue" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicSubscriptionsResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSubscriptionsResource" } } } } } } }, "/brands/{brand}/traffic": { "get": { "operationId": "public.revenue.traffic", "description": "Sessions and conversions the AI assistants (ChatGPT, Claude, Gemini,\nPerplexity\u2026) send to the site, per surface and per week, vs the whole\nsite \u2014 measured by the Skoup script installed on it, the figures of\nthe \u00ab AI traffic \u00bb screen \u2014 and the conversions whose first touch was\nan assistant. The blocks are `null` until the script brought a visit.", "summary": "Retrieve the AI traffic", "tags": [ "Revenue" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicTrafficResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTrafficResource" } } } } } } }, "/brands/{brand}/samplings": { "get": { "operationId": "public.samplings.index", "description": "The measurements of the brand, newest first: the weekly samplings of\neach market and the targeted re-samplings of a single query.", "summary": "List samplings", "tags": [ "Samplings" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "market", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicSamplingResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicSamplingResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } } }, "/brands/{brand}/samplings/{sampling}": { "get": { "operationId": "public.samplings.show", "summary": "Retrieve a sampling", "tags": [ "Samplings" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "sampling", "in": "path", "required": true, "description": "Sampling id (`smp_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicSamplingResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSamplingResource" } } } } } } }, "/brands/{brand}/tasks": { "get": { "operationId": "public.tasks.index", "description": "The backlog of fixes of a brand, newest first.", "summary": "List tasks", "tags": [ "Tasks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `PublicTaskResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTaskResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } }, "post": { "operationId": "public.tasks.store", "description": "Adds a manual fix to the backlog, in the `todo` column.", "summary": "Create a task", "tags": [ "Tasks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStoreTaskRequest" } } } }, "responses": { "201": { "description": "`PublicTaskResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTaskResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/tasks/{task}": { "get": { "operationId": "public.tasks.show", "summary": "Retrieve a task", "tags": [ "Tasks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "task", "in": "path", "required": true, "description": "Task id (`task_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicTaskResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTaskResource" } } } } } }, "patch": { "operationId": "public.tasks.update", "description": "Updates its fields and/or moves it on the kanban with `status` \u2014 one\ncolumn at a time (`invalid_transition` otherwise). Moving to\n`verified` may record the measured `gain`. A refused move changes nothing.", "summary": "Update a task", "tags": [ "Tasks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "task", "in": "path", "required": true, "description": "Task id (`task_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpdateTaskRequest" } } } }, "responses": { "200": { "description": "`PublicTaskResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTaskResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/brands/{brand}/tasks/{task}/plan": { "get": { "operationId": "public.tasks.plan", "description": "The step-by-step plan a model wrote for the task in the app, adapted to\nthe brand's platform and to the task's evidence. Read only: plans are\nwritten on demand from the app, never through the API. `resource_missing`\nuntil one was written.", "summary": "Retrieve a task's plan", "tags": [ "Tasks" ], "parameters": [ { "name": "brand", "in": "path", "required": true, "description": "Brand id (`br_\u2026`).", "schema": { "type": "string" } }, { "name": "task", "in": "path", "required": true, "description": "Task id (`task_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicTaskPlanResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTaskPlanResource" } } } } } } }, "/webhook_endpoints": { "get": { "operationId": "public.webhook_endpoints.index", "summary": "List webhook endpoints", "tags": [ "Webhook endpoints", "WebhookEndpoints" ], "responses": { "200": { "description": "Array of `PublicWebhookEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWebhookEndpointResource" } }, "object": { "type": "string", "const": "list" }, "has_more": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "data", "object", "has_more", "url" ] } } } } } }, "post": { "operationId": "public.webhook_endpoints.store", "description": "The response carries the signing `secret` (`whsec_\u2026`) \u2014 the only time\nthe API returns it. Store it to verify the `X-Skoup-Signature` header.", "summary": "Create a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "`PublicWebhookEndpointResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEndpointResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/webhook_endpoints/{endpoint}": { "get": { "operationId": "public.webhook_endpoints.show", "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoints" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Webhook Endpoint id (`we_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`PublicWebhookEndpointResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEndpointResource" } } } } } }, "patch": { "operationId": "public.webhook_endpoints.update", "description": "Send `disabled: true` to pause it, `false` to enable it again.", "summary": "Update a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoints" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Webhook Endpoint id (`we_\u2026`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "`PublicWebhookEndpointResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWebhookEndpointResource" } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "public.webhook_endpoints.destroy", "summary": "Delete a webhook endpoint", "tags": [ "Webhook endpoints", "WebhookEndpoints" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "Webhook Endpoint id (`we_\u2026`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "deleted": { "type": "boolean" } }, "required": [ "id", "object", "deleted" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer", "bearerFormat": "skoup_live_\u2026 / skoup_test_\u2026" } }, "schemas": { "AiModel": { "type": "string", "description": "The AI assistants Skoup samples. Keys match the front's `lib/ai-models.ts` and the `--model-*` tokens; model ids and providers live in config('skoup.visibility').\n", "enum": [ "chatgpt", "claude", "gemini", "perplexity", "grok", "mistral", "deepseek", "qwen" ], "title": "AiModel" }, "AlertCloseReason": { "type": "string", "description": "Why Skoup itself closed an alert. `Rejudged`: the way a claim is judged changed and this one no longer counts as wrong \u2014 never a fix the brand made, so never \u00ab resolved \u00bb.\n", "enum": [ "rejudged" ], "title": "AlertCloseReason" }, "AlertKind": { "type": "string", "description": "What an alert reports. Adding a kind = one case here, one detector and the copy; the inbox is data-driven.\n", "enum": [ "price_hallucination", "wrong_availability", "visibility_drop", "new_competitor", "spec_invented", "wrong_local_fact", "seo_regression" ], "title": "AlertKind" }, "AlertSeverity": { "type": "string", "enum": [ "critical", "medium", "low" ], "title": "AlertSeverity" }, "AlertStatus": { "type": "string", "description": "Lifecycle of an alert (mockup): Nouvelle \u2192 Vue \u2192 Trait\u00e9e \u2192 R\u00e9solue v\u00e9rifi\u00e9e, plus Ignor\u00e9e on the side. `Resolved` is only ever reached by a verification re-sampling (ResolveVerifiedAlerts), never by the API.\n", "enum": [ "new", "seen", "treated", "resolved", "ignored" ], "title": "AlertStatus" }, "AttributionSignal": { "type": "string", "description": "Which of the store's origin fields proved the AI surface of an order. NULL on the order = no AI signal (the referrer host is still kept).\n| |\n|---|\n| `referrer`
The session's referrer is an assistant's domain. |\n| `utm`
The landing URL carries a `utm_source` naming an assistant (ChatGPT tags its links). |\n| `landing_ref`
Shopify's `landing_site_ref` (`?ref=`) names an assistant. |", "enum": [ "referrer", "utm", "landing_ref" ], "title": "AttributionSignal" }, "BrandPlatform": { "type": "string", "description": "What the brand's site runs on. Chosen by a person (onboarding, R\u00e9glages \u2192 Marque, an agency adding the brand), set by a connected integration, or detected from the site's crawl (Seo\\Services\\PlatformDetector) \u2014 see BrandPlatformSource. Only Shopify has a connector; the others tell the fix plans which admin to walk through. `custom` = a site built in-house.\n", "enum": [ "shopify", "woocommerce", "prestashop", "magento", "bigcommerce", "wix", "squarespace", "webflow", "wordpress", "custom" ], "title": "BrandPlatform" }, "CompetitorOrigin": { "type": "string", "description": "How a competitor entered the referential. - detected \u2192 suggested by the sampling (it was already cited in answers) - declared \u2192 typed by a user, by brand name or domain\n", "enum": [ "detected", "declared" ], "title": "CompetitorOrigin" }, "LocationSource": { "type": "string", "description": "Where an establishment row came from: read on the brand's site, or typed by an editor.\n", "enum": [ "site", "manual" ], "title": "LocationSource" }, "MarketSource": { "type": "string", "description": "Where a brand market comes from: detected in the connected store (Shopify Markets) or added by hand on \u00ab Catalogue \u00b7 March\u00e9s \u00bb.\n", "enum": [ "shopify", "manual" ], "title": "MarketSource" }, "MarketStatus": { "type": "string", "description": "Lifecycle of a brand market, as shown by the navbar market chips. - active \u2192 sampled every cycle, selectable everywhere. - backfill \u2192 just activated, history being rebuilt; selectable, flagged. - off \u2192 detected (Shopify Markets\u2026) but not activated; greyed out.\n", "enum": [ "active", "backfill", "off" ], "title": "MarketStatus" }, "OrderSource": { "type": "string", "description": "The store an order was received from. Shopify today (orders/create webhook); WooCommerce / PrestaShop land here with their plugins.\n", "enum": [ "shopify" ], "title": "OrderSource" }, "PricePeriod": { "type": "string", "description": "What a price buys: a month or a year of a subscription, or the thing once. Shared by the catalogue and by the price an answer states \u2014 two prices of different periods are never compared.\n", "enum": [ "month", "year", "once" ], "title": "PricePeriod" }, "PriceUnit": { "type": "string", "description": "What a price is counted by: the whole offer, or each user (seat, practitioner, workstation). Shared by the catalogue and by the price an answer states.\n", "enum": [ "flat", "per_user" ], "title": "PriceUnit" }, "ProductSource": { "type": "string", "description": "Where a product comes from. Synced sources (Shopify, a CSV / XML feed, later WooCommerce / PrestaShop) are the source of truth: their products are read-only in Skoup and refreshed by the sync. Manual products are fully editable, and so are the offerings read on the brand's site by the site profile (`site`): a suggestion the customer edits, never overwritten once touched.\n", "enum": [ "shopify", "feed", "manual", "site" ], "title": "ProductSource" }, "ProductStatus": { "type": "string", "description": "Publication status, aligned on Shopify's product statuses so a synced product maps one-to-one.\n", "enum": [ "active", "draft", "archived" ], "title": "ProductStatus" }, "PromptIntent": { "type": "string", "description": "The shopping-query templates of the spec: \u00ab meilleur X \u00bb, \u00ab X vs Z \u00bb, \u00ab alternatives \u00e0 X \u00bb. Detected on manual prompts, explicit on generated ones; anything else is custom.\n", "enum": [ "best_x", "x_vs_z", "alternatives_to_x", "custom" ], "title": "PromptIntent" }, "PromptSource": { "type": "string", "description": "| |\n|---|\n| `generated`
Generated from the catalog at onboarding / re-generation. |\n| `manual`
Added by hand in the prompt panel. |", "enum": [ "generated", "manual" ], "title": "PromptSource" }, "PublicAlertResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "alert" }, "brand": { "type": "string" }, "market": { "type": "string" }, "kind": { "$ref": "#/components/schemas/AlertKind" }, "severity": { "$ref": "#/components/schemas/AlertSeverity" }, "status": { "$ref": "#/components/schemas/AlertStatus" }, "product": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, "query": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "text": { "type": "string" } }, "required": [ "id", "text" ] }, "competitor": { "type": [ "string", "null" ] }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "city" ] }, "model": { "anyOf": [ { "$ref": "#/components/schemas/AiModel" }, { "type": "null" } ] }, "models": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "occurrences": { "type": "integer" } }, "required": [ "model", "occurrences" ] } }, "occurrences": { "type": "integer" }, "claimed": { "type": "object", "additionalProperties": {} }, "truth": { "type": [ "object", "null" ], "additionalProperties": {} }, "persisted": { "type": "boolean", "description": "The claim survived the last verification re-sampling." }, "verifications": { "type": "integer" }, "first_seen_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "treated_at": { "type": [ "string", "null" ] }, "dismissed_at": { "type": [ "string", "null" ] }, "close_reason": { "anyOf": [ { "$ref": "#/components/schemas/AlertCloseReason" }, { "type": "null" } ] }, "last_verification_at": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "brand", "market", "kind", "severity", "status", "product", "query", "competitor", "location", "model", "models", "occurrences", "claimed", "truth", "persisted", "verifications", "first_seen_at", "last_seen_at", "treated_at", "dismissed_at", "close_reason", "last_verification_at", "resolved_at", "livemode", "created" ], "title": "PublicAlertResource" }, "PublicAttributionResource": { "type": "object", "properties": { "object": { "type": "string", "const": "attribution" }, "brand": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "ai": { "type": [ "object", "null" ], "properties": { "orders": { "type": "string" }, "revenue": { "type": "string" }, "average_basket": { "type": "string" }, "share_of_revenue": { "type": "string" }, "share_of_orders": { "type": "string" }, "previous_orders": { "type": "string" }, "previous_revenue": { "type": "string" }, "revenue_change": { "type": "string" } }, "required": [ "orders", "revenue", "average_basket", "share_of_revenue", "share_of_orders", "previous_orders", "previous_revenue", "revenue_change" ] }, "store": { "type": [ "object", "null" ], "properties": { "orders": { "type": "string" }, "revenue": { "type": "string" }, "average_basket": { "type": "string" } }, "required": [ "orders", "revenue", "average_basket" ] }, "surfaces": { "type": "array", "items": {} }, "products": { "type": "array", "items": {} }, "first_touch": { "type": [ "object", "null" ], "description": "Orders the Skoup pixel joined to their visit: the buyer's first AI contact.", "properties": { "window_days": { "type": "string" }, "orders": { "type": "string" }, "ai_orders": { "type": "string" }, "ai_share": { "type": "string" }, "ai_revenue": { "type": "string" }, "surfaces": { "type": "array", "items": {} } }, "required": [ "window_days", "orders", "ai_orders", "ai_share", "ai_revenue", "surfaces" ] }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "period", "currency", "from", "to", "ai", "store", "surfaces", "products", "first_touch", "livemode" ], "title": "PublicAttributionResource" }, "PublicBrandMetricsResource": { "type": "object", "properties": { "object": { "type": "string", "const": "brand_metrics" }, "brand": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "visibility": { "type": "string" }, "accuracy": { "type": "string" }, "readiness": { "type": "string" }, "perception": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "period", "visibility", "accuracy", "readiness", "perception", "livemode" ], "title": "PublicBrandMetricsResource" }, "PublicBrandResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "brand" }, "name": { "type": "string" }, "slug": { "type": "string" }, "vertical": { "type": "string", "description": "What the brand sells: products, software / online services, or a physical establishment." }, "site_url": { "type": [ "string", "null" ] }, "logo_url": { "type": "string", "description": "Signed URL, valid 60 minutes." }, "platform": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "name", "slug", "vertical", "site_url", "logo_url", "platform", "livemode", "created" ], "title": "PublicBrandResource" }, "PublicCompetitorResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "competitor" }, "name": { "type": "string" }, "key": { "type": "string", "description": "Normalized identity of the brand in the answers (stable across spellings)." }, "domain": { "type": [ "string", "null" ] }, "market": { "type": "string" }, "origin": { "$ref": "#/components/schemas/CompetitorOrigin" }, "tracked": { "type": "boolean" }, "tracked_at": { "type": "string" }, "removed_at": { "type": [ "string", "null" ] }, "visibility": {}, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "name", "key", "domain", "market", "origin", "tracked", "tracked_at", "removed_at", "livemode", "created" ], "title": "PublicCompetitorResource" }, "PublicCorrelationResource": { "type": "object", "properties": { "object": { "type": "string", "const": "visibility_revenue_correlation" }, "brand": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "category": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": {} }, "weeks": { "type": "array", "items": {} }, "fixes": { "type": "array", "items": {} }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "period", "category", "currency", "categories", "weeks", "fixes", "livemode" ], "title": "PublicCorrelationResource" }, "PublicEventResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string" }, "api_version": { "type": "string" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." }, "livemode": { "type": "boolean" }, "brand": { "type": [ "string", "null" ] }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {} }, "previous_attributes": { "type": "object", "additionalProperties": {} } }, "required": [ "object" ] } }, "required": [ "id", "object", "type", "api_version", "created", "livemode", "brand", "data" ], "title": "PublicEventResource" }, "PublicLocationResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "location" }, "brand": { "type": "string" }, "market": { "type": "string", "description": "The market's ISO 3166-1 alpha-2 code, e.g. `FR`." }, "name": { "type": "string" }, "city": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "opening_hours": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/LocationSource" }, "tracked": { "type": "boolean", "description": "Whether the query panel writes queries for it." }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "brand", "market", "name", "city", "region", "postal_code", "address", "phone", "opening_hours", "url", "source", "tracked", "livemode", "created" ], "title": "PublicLocationResource" }, "PublicMarketResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "market" }, "brand": { "type": "string" }, "code": { "type": "string", "description": "ISO 3166-1 alpha-2, e.g. `FR` \u2014 the `market` parameter of the other endpoints." }, "language": { "type": "string" }, "currency": { "type": "string" }, "status": { "$ref": "#/components/schemas/MarketStatus" }, "source": { "$ref": "#/components/schemas/MarketSource" }, "domain": { "type": [ "string", "null" ] }, "locality": { "type": [ "object", "null" ], "properties": { "city": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "opening_hours": { "type": [ "string", "null" ] } }, "required": [ "city", "region", "address", "phone", "opening_hours" ] }, "is_primary": { "type": "boolean" }, "activated_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "brand", "code", "language", "currency", "status", "source", "domain", "locality", "is_primary", "activated_at", "livemode", "created" ], "title": "PublicMarketResource" }, "PublicOrderResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "order" }, "source": { "$ref": "#/components/schemas/OrderSource" }, "order_number": { "type": [ "string", "null" ] }, "ordered_at": { "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": [ "string", "null" ] }, "total": { "type": "string" }, "items_count": { "type": "integer" }, "country": { "type": [ "string", "null" ] }, "ai_surface": { "type": [ "string", "null" ], "description": "Key of the AI surface the order is attributed to (chatgpt, claude, gemini, perplexity\u2026), null = not attributed." }, "attribution_signal": { "anyOf": [ { "$ref": "#/components/schemas/AttributionSignal" }, { "type": "null" } ] }, "referrer_host": { "type": [ "string", "null" ] }, "landing_path": { "type": [ "string", "null" ] }, "landing_product": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_campaign": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": [ "string", "null" ], "description": "Null when the line matches no product of the catalogue." }, "title": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": [ "string", "null" ] }, "total": { "type": "string" } }, "required": [ "product", "title", "sku", "quantity", "unit_price", "total" ] } }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "source", "order_number", "ordered_at", "currency", "subtotal", "total", "items_count", "country", "ai_surface", "attribution_signal", "referrer_host", "landing_path", "landing_product", "utm_source", "utm_medium", "utm_campaign", "lines", "livemode", "created" ], "title": "PublicOrderResource" }, "PublicProductPerceptionResource": { "type": "object", "properties": { "object": { "type": "string", "const": "product_perception" }, "product": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "sheet_version": { "type": "string" }, "score": { "type": "string" }, "counts": { "type": "string" }, "by_model": { "type": "string" }, "attributes": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "object", "product", "market", "period", "sheet_version", "score", "counts", "by_model", "attributes", "livemode" ], "title": "PublicProductPerceptionResource" }, "PublicProductRequest": { "type": "object", "description": "POST / PATCH of a manual product \u2014 same fields as the app's product form.", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "vendor": { "type": [ "string", "null" ], "maxLength": 120 }, "sku": { "type": [ "string", "null" ], "maxLength": 120 }, "gtin": { "type": [ "string", "null" ], "maxLength": 120 }, "price": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9999999999.99 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 60 }, "maxItems": 50 }, "price_period": { "anyOf": [ { "$ref": "#/components/schemas/PricePeriod" }, { "type": "null" } ] }, "price_annual": { "type": [ "number", "null" ], "description": "Always the amount of one year, whatever the way the site writes it.", "minimum": 0, "maximum": 9999999999.99 }, "price_unit": { "anyOf": [ { "$ref": "#/components/schemas/PriceUnit" }, { "type": "null" } ] }, "addons": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "price": { "type": [ "number", "null" ], "description": "Null = on quote.", "minimum": 0, "maximum": 9999999999.99 }, "period": { "anyOf": [ { "$ref": "#/components/schemas/PricePeriod" }, { "type": "null" } ] }, "unit": { "anyOf": [ { "$ref": "#/components/schemas/PriceUnit" }, { "type": "null" } ] } }, "required": [ "name", "price" ] }, "maxItems": 12 } }, "required": [ "title" ], "title": "PublicProductRequest" }, "PublicProductResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "product" }, "brand": { "type": "string" }, "source": { "$ref": "#/components/schemas/ProductSource" }, "read_only": { "type": "boolean" }, "external_id": { "type": [ "string", "null" ], "description": "Identifier at the source (e.g. a Shopify GID), null for manual products." }, "handle": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "vendor": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ], "description": "Decimal string, e.g. \"1299.00\"." }, "currency": { "type": [ "string", "null" ] }, "price_period": { "anyOf": [ { "$ref": "#/components/schemas/PricePeriod" }, { "type": "null" } ] }, "price_annual": { "type": [ "string", "null" ], "description": "Always the amount of one year, decimal string." }, "price_unit": { "anyOf": [ { "$ref": "#/components/schemas/PriceUnit" }, { "type": "null" } ] }, "addons": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "period": { "type": [ "string", "null" ], "enum": [ "month", "year", "once", null ] }, "unit": { "type": [ "string", "null" ], "enum": [ "flat", "per_user", null ] } }, "required": [ "name", "price", "period", "unit" ] } }, "url": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ProductStatus" }, "tags": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "values" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "variant" }, "title": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "price": { "type": [ "string", "null" ] }, "compare_at_price": { "type": [ "string", "null" ] }, "inventory_quantity": { "type": [ "integer", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } }, "required": [ "id", "object", "title", "sku", "gtin", "price", "compare_at_price", "inventory_quantity", "options" ] } }, "synced_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." }, "updated": { "type": "string" } }, "required": [ "id", "object", "brand", "source", "read_only", "external_id", "handle", "title", "description", "vendor", "category", "sku", "gtin", "price", "currency", "price_period", "price_annual", "price_unit", "addons", "url", "image_url", "status", "tags", "options", "variants", "synced_at", "livemode", "created", "updated" ], "title": "PublicProductResource" }, "PublicQueryResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "query" }, "text": { "type": "string" }, "market": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "intent": { "$ref": "#/components/schemas/PromptIntent" }, "source": { "$ref": "#/components/schemas/PromptSource" }, "enabled": { "type": "boolean" }, "visibility": { "description": "Share (%) of the answers citing the brand over the period \u2014 null before any measurement." }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "text", "market", "category", "intent", "source", "enabled", "visibility", "livemode", "created" ], "title": "PublicQueryResource" }, "PublicReadinessScoreResource": { "type": "object", "properties": { "object": { "type": "string", "const": "readiness_score" }, "brand": { "type": "string" }, "market": { "type": [ "string", "null" ] }, "score": { "type": [ "integer", "null" ] }, "previous_score": {}, "trigger": { "$ref": "#/components/schemas/ReadinessTrigger" }, "blocks": { "type": "array", "items": {} }, "computed_at": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "score", "previous_score", "trigger", "blocks", "computed_at", "livemode" ], "title": "PublicReadinessScoreResource" }, "PublicSamplingResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "sampling" }, "market": { "type": "string" }, "trigger": { "$ref": "#/components/schemas/SamplingTrigger" }, "status": { "$ref": "#/components/schemas/SamplingStatus" }, "query": { "type": [ "string", "null" ] }, "week_starts_on": { "type": "string" }, "models": { "type": "array", "items": {} }, "queries_count": { "type": "integer" }, "runs_total": { "type": "integer" }, "runs_completed": { "type": "integer" }, "runs_failed": { "type": "integer" }, "brand_share": { "description": "Share (%) of the answers citing the brand \u2014 null until the sampling is finalized." }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string" }, "runs": { "type": "integer" }, "hits": { "type": "integer" }, "avg_position": { "type": [ "number", "null" ] } }, "required": [ "model", "runs", "hits", "avg_position" ] } }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "market", "trigger", "status", "query", "week_starts_on", "models", "queries_count", "runs_total", "runs_completed", "runs_failed", "brand_share", "by_model", "error", "started_at", "finished_at", "livemode", "created" ], "title": "PublicSamplingResource" }, "PublicSourceGapResource": { "type": "object", "properties": { "object": { "type": "string", "const": "source_gap" }, "host": { "type": "string", "description": "The site, without `www.`. @example bikeradar.com" }, "category": { "type": "string", "enum": [ "reseller", "forum", "video", "media" ] }, "answers_without_brand": { "description": "Answers citing the site that name a competitor and not the brand, over the period.", "type": "number" }, "answers_with_brand": { "description": "Answers citing the site that name the brand, over the period.", "type": "number" }, "queries": { "type": "string", "description": "Distinct queries behind `answers_without_brand`." }, "competitors": { "type": "array", "description": "The competitor brands named most often alongside the site.", "items": { "type": "string" } }, "pages": { "type": "array", "description": "Up to three pages of the site the answers cite.", "items": { "type": "string" } }, "last_cited_at": { "type": "string", "description": "ISO-8601 UTC." }, "has_open_task": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "object", "host", "category", "answers_without_brand", "answers_with_brand", "queries", "competitors", "pages", "last_cited_at", "has_open_task", "livemode" ], "title": "PublicSourceGapResource" }, "PublicStoreQueryRequest": { "type": "object", "description": "POST /v1/brands/{brand}/queries \u2014 the scope is checked by the route.", "properties": { "text": { "type": "string", "maxLength": 300 }, "market": { "type": "string", "description": "An activated market of the brand (ISO 3166-1 alpha-2).", "minLength": 2, "maxLength": 2 }, "category": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "text", "market" ], "title": "PublicStoreQueryRequest" }, "PublicStoreTaskRequest": { "type": "object", "description": "POST /v1/brands/{brand}/tasks \u2014 the scope is checked on the route. No\nassignee: the public API never exposes workspace members.", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "kind": { "$ref": "#/components/schemas/TaskKind" }, "effort": { "anyOf": [ { "$ref": "#/components/schemas/TaskEffort" }, { "type": "null" } ] }, "product": { "type": [ "string", "null" ], "maxLength": 120 }, "impact": { "type": [ "string", "null" ], "maxLength": 120 }, "source_label": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "title", "kind" ], "title": "PublicStoreTaskRequest" }, "PublicSubscriptionsResource": { "type": "object", "properties": { "object": { "type": "string", "const": "ai_subscriptions" }, "brand": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "last_synced_at": { "type": "string" }, "currency": { "type": "string" }, "new": { "type": [ "object", "null" ], "properties": { "subscriptions": { "type": "string" }, "mrr": { "type": "string" }, "previous_subscriptions": { "type": "string" } }, "required": [ "subscriptions", "mrr", "previous_subscriptions" ] }, "ai": { "type": [ "object", "null" ], "properties": { "subscriptions": { "type": "string" }, "mrr": { "type": "string" }, "share_of_subscriptions": { "type": "string" }, "share_of_mrr": { "type": "string" }, "previous_subscriptions": { "type": "string" } }, "required": [ "subscriptions", "mrr", "share_of_subscriptions", "share_of_mrr", "previous_subscriptions" ] }, "tracked_share": { "type": "string" }, "surfaces": { "type": "array", "items": {} }, "weeks": { "type": "array", "items": {} }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "period", "from", "to", "last_synced_at", "currency", "new", "ai", "tracked_share", "surfaces", "weeks", "livemode" ], "title": "PublicSubscriptionsResource" }, "PublicTaskPlanResource": { "type": "object", "properties": { "object": { "type": "string", "const": "task_plan" }, "task": { "type": "string" }, "status": { "$ref": "#/components/schemas/TaskPlanStatus" }, "content": { "type": [ "object", "null" ], "properties": { "summary": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "detail": { "type": "string" }, "where": { "type": [ "string", "null" ] } }, "required": [ "title", "detail", "where" ] } }, "verification": { "type": "string" }, "caveats": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "steps", "verification", "caveats" ] }, "platform": { "anyOf": [ { "$ref": "#/components/schemas/BrandPlatform" }, { "type": "null" } ] }, "locale": { "type": "string" }, "generated_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" } }, "required": [ "object", "task", "status", "content", "platform", "locale", "generated_at", "livemode" ], "title": "PublicTaskPlanResource" }, "PublicTaskResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "task" }, "brand": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "kind": { "$ref": "#/components/schemas/TaskKind" }, "effort": { "anyOf": [ { "$ref": "#/components/schemas/TaskEffort" }, { "type": "null" } ] }, "source": { "$ref": "#/components/schemas/TaskSource" }, "source_label": { "type": [ "string", "null" ] }, "alert": { "type": [ "string", "null" ], "description": "The alert the task was created from (`alrt_\u2026`), when source = alert." }, "product": { "type": [ "string", "null" ] }, "impact": { "type": [ "string", "null" ] }, "gain": { "type": [ "string", "null" ] }, "guide": { "type": [ "object", "null" ], "properties": { "topic": { "type": "string" }, "platform": { "type": "string", "enum": [ "shopify", "generic" ] }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "topic", "platform", "steps" ] }, "assignee": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "started_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "verify_at": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." }, "updated": { "type": "string" } }, "required": [ "id", "object", "brand", "title", "description", "status", "kind", "effort", "source", "source_label", "alert", "product", "impact", "gain", "guide", "assignee", "started_at", "published_at", "verify_at", "verified_at", "livemode", "created", "updated" ], "title": "PublicTaskResource" }, "PublicTrafficResource": { "type": "object", "properties": { "object": { "type": "string", "const": "ai_traffic" }, "brand": { "type": "string" }, "market": { "type": "string" }, "period": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "last_hit_at": { "type": "string" }, "conversion_metric": { "type": [ "string", "null" ], "enum": [ "transactions", "key_events", null ] }, "ai": { "type": [ "object", "null" ], "properties": { "sessions": { "type": "string" }, "transactions": { "type": "string" }, "key_events": { "type": "string" }, "conversion_rate": { "type": "string" }, "share_of_sessions": { "type": "string" }, "previous_sessions": { "type": "string" }, "sessions_change": { "type": "string" } }, "required": [ "sessions", "transactions", "key_events", "conversion_rate", "share_of_sessions", "previous_sessions", "sessions_change" ] }, "site": { "type": [ "object", "null" ], "properties": { "sessions": { "type": "string" }, "transactions": { "type": "string" }, "key_events": { "type": "string" }, "conversion_rate": { "type": "string" } }, "required": [ "sessions", "transactions", "key_events", "conversion_rate" ] }, "surfaces": { "type": "array", "items": {} }, "weeks": { "type": "array", "items": {} }, "first_touch": { "type": [ "object", "null" ], "properties": { "window_days": { "type": "string" }, "conversions": { "type": "string" }, "ai_conversions": { "type": "string" }, "ai_share": { "type": "string" }, "surfaces": { "type": "array", "items": {} } }, "required": [ "window_days", "conversions", "ai_conversions", "ai_share", "surfaces" ] }, "livemode": { "type": "boolean" } }, "required": [ "object", "brand", "market", "period", "from", "to", "last_hit_at", "conversion_metric", "ai", "site", "surfaces", "weeks", "first_touch", "livemode" ], "title": "PublicTrafficResource" }, "PublicUpdateQueryRequest": { "type": "object", "description": "PATCH /v1/brands/{brand}/queries/{query} \u2014 re-enabling goes through the quota.", "properties": { "text": { "type": "string", "maxLength": 300 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "enabled": { "type": "boolean" } }, "title": "PublicUpdateQueryRequest" }, "PublicUpdateTaskRequest": { "type": "object", "description": "PATCH /v1/brands/{brand}/tasks/{task} \u2014 editable fields and/or `status`\n(one kanban column at a time) with the measured `gain` when verifying.", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "kind": { "$ref": "#/components/schemas/TaskKind" }, "effort": { "anyOf": [ { "$ref": "#/components/schemas/TaskEffort" }, { "type": "null" } ] }, "product": { "type": [ "string", "null" ], "maxLength": 120 }, "impact": { "type": [ "string", "null" ], "maxLength": 120 }, "source_label": { "type": [ "string", "null" ], "maxLength": 120 }, "verify_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "gain": { "type": [ "string", "null" ], "maxLength": 200 } }, "title": "PublicUpdateTaskRequest" }, "PublicWebhookEndpointRequest": { "type": "object", "description": "Body of POST / PATCH /v1/webhook_endpoints. Brands are public `br_` ids;\nevent types are checked against the catalog by SaveWebhookEndpoint.", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "enabled_events": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "minItems": 1 }, "brands": { "type": [ "array", "null" ], "items": { "type": "string" } }, "disabled": { "type": "boolean" } }, "required": [ "url", "enabled_events" ], "title": "PublicWebhookEndpointRequest" }, "PublicWebhookEndpointResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled_events": { "type": "array", "items": { "type": "string" } }, "brands": { "type": [ "array", "null" ], "items": {} }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "api_version": { "type": "string" }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." }, "secret": { "type": "string" } }, "required": [ "id", "object", "url", "description", "enabled_events", "brands", "status", "api_version", "livemode", "created" ], "title": "PublicWebhookEndpointResource" }, "PublicWriteBackResource": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "write_back" }, "brand": { "type": "string" }, "product": { "type": "string" }, "task": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/WriteBackStatus" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "description_html", "seo_title", "seo_description", "barcode" ] }, "variant_external_id": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] }, "before": { "type": "string" }, "after": { "type": "string" } }, "required": [ "field", "variant_external_id", "variant_title", "before", "after" ] } }, "error": { "type": [ "string", "null" ] }, "applied_at": { "type": [ "string", "null" ] }, "rollback_until": { "type": [ "string", "null" ], "description": "Last moment a rollback is possible (in the app); NULL once rolled back or failed." }, "rolled_back_at": { "type": [ "string", "null" ] }, "livemode": { "type": "boolean" }, "created": { "type": "integer", "description": "Time at which the object was created (unix timestamp, seconds)." } }, "required": [ "id", "object", "brand", "product", "task", "status", "changes", "error", "applied_at", "rollback_until", "rolled_back_at", "livemode", "created" ], "title": "PublicWriteBackResource" }, "ReadinessTrigger": { "type": "string", "enum": [ "crawl", "sync", "declaration", "manual", "seed" ], "title": "ReadinessTrigger" }, "SamplingStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ], "title": "SamplingStatus" }, "SamplingTrigger": { "type": "string", "description": "What started a sampling. `onboarding` is the first sampling of a brand, launched when the owner closes the stepper (day 0). `targeted` re-runs a single query from the query drawer \u2014 it always carries a `prompt_id`.\n", "enum": [ "onboarding", "scheduled", "manual", "targeted" ], "title": "SamplingTrigger" }, "TaskEffort": { "type": "string", "description": "T-shirt sizing shown on the kanban cards (S \u00b7 < 1 h, M \u00b7 \u00bd journ\u00e9e, L \u00b7 2-3 j).\n", "enum": [ "s", "m", "l" ], "title": "TaskEffort" }, "TaskKind": { "type": "string", "description": "Nature of the fix \u2014 matches the mockup filter pills (Write-back / Contenu / Technique). Write-back = applicable in one click on a Shopify product (description, SEO, barcode \u2014 SKO-151); everything else is done by hand, with a guide.\n", "enum": [ "writeback", "content", "technical" ], "title": "TaskKind" }, "TaskPlanStatus": { "type": "string", "description": "A fix plan being written (`pending`), written (`ready`), or not written (`failed`: no provider key, the model failed or answered nothing usable \u2014 the task keeps its fixed guide, nothing is invented).\n", "enum": [ "pending", "ready", "failed" ], "title": "TaskPlanStatus" }, "TaskSource": { "type": "string", "description": "Where the task came from: created by hand (\"+ Correctif manuel\"), from a failing SEO or readiness check, from an alert, from a vacant territory on the Concurrents screen, or from a source the assistants cite without the brand (\u00ab Sources \u00e0 conqu\u00e9rir \u00bb).\n", "enum": [ "manual", "seo_check", "alert", "readiness", "opportunity", "perception", "source_gap" ], "title": "TaskSource" }, "TaskStatus": { "type": "string", "description": "Kanban columns of the \"\u00c0 traiter\" screen, in board order: \u00c0 faire \u2192 En cours \u2192 En v\u00e9rification \u2192 V\u00e9rifi\u00e9. Transitions move one column at a time (the card CTA moves forward, the \"\u2190\" button moves back); a verified task is terminal.\n", "enum": [ "todo", "in_progress", "in_verification", "verified" ], "title": "TaskStatus" }, "WriteBackStatus": { "type": "string", "description": "- applied \u2192 written in the store; reversible until `rollback_until`. - rolled_back \u2192 the \u00ab before \u00bb values were written back. - failed \u2192 Shopify refused the write, nothing changed at the store.\n", "enum": [ "applied", "rolled_back", "failed" ], "title": "WriteBackStatus" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }