{ "openapi": "3.0.3", "info": { "title": "Searchly API", "version": "1.0.0", "description": "Owner-managed, workspace-bound API keys. Enable API access explicitly when creating a key in Settings. Feature entitlements, job admission, revision checks, and publishing approvals match the platform. OAuth consent remains interactive." }, "servers": [ { "url": "https://app.trysearchly.com/api/v1" } ], "paths": { "/workspace": { "get": { "operationId": "getWorkspace", "summary": "Read workspace plan, limits, and usage", "description": "In the limits object, crawler_access, api_access, and mcp_access are reserved fields. They are false on every plan, may be omitted, and do not show whether API, MCP, or crawler access is enabled for the workspace.", "tags": [ "workspace" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/engines": { "get": { "operationId": "listEngines", "summary": "List active measurement engines", "tags": [ "engines" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List workspace projects", "tags": [ "projects" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project within plan limits", "tags": [ "projects" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "country": { "type": "string", "minLength": 1, "maxLength": 64 }, "language": { "type": "string", "pattern": "^[A-Za-z]{2,3}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name", "url", "country", "language", "timezone" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Read a project's configuration and tracking state", "tags": [ "projects" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateProject", "summary": "Update project settings", "tags": [ "projects" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "country": { "type": "string", "minLength": 1, "maxLength": 64 }, "language": { "type": "string", "pattern": "^[A-Za-z]{2,3}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 }, "location": { "type": "string", "maxLength": 500 }, "geographicReach": { "type": "string", "maxLength": 500 }, "brandContext": { "type": "string", "maxLength": 12000 }, "exactMatch": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/activate": { "post": { "operationId": "activateProject", "summary": "Activate project tracking with existing subscription checks", "tags": [ "activate" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analysis": { "post": { "operationId": "startProjectAnalysis", "summary": "Prepare and enqueue today's project analysis", "description": "Uses the existing enrichment, spend, and queue guards. An accepted request does not mean the analysis is complete.", "tags": [ "analysis" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getProjectAnalysisStatus", "summary": "Read truthful analysis and report readiness", "tags": [ "analysis" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/enrich": { "post": { "operationId": "enrichProject", "summary": "Enrich a project using existing guarded provider behavior", "tags": [ "enrich" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompt-allocation": { "put": { "operationId": "setProjectPromptAllocation", "summary": "Set this project's share of the workspace prompt budget", "tags": [ "prompt-allocation" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promptLimit": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false } }, "required": [ "promptLimit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/engines": { "put": { "operationId": "setProjectEngines", "summary": "Select measurement engines within plan entitlements", "tags": [ "engines" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "engines": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "minItems": 1, "maxItems": 20 } }, "required": [ "engines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/brand-profile": { "get": { "operationId": "getBrandProfile", "summary": "Read brand profile and writing guidance", "tags": [ "brand-profile" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/brand-profile/{field}": { "put": { "operationId": "setBrandProfileField", "summary": "Update one brand writing-guidance field", "tags": [ "brand-profile" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "summary", "about", "icp", "pointOfView", "eeat", "tone", "writingStyle", "memory" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "maxLength": 12000 } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/competitors": { "get": { "operationId": "listCompetitors", "summary": "List tracked competitors", "tags": [ "competitors" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addCompetitor", "summary": "Add a tracked competitor with existing duplicate checks", "tags": [ "competitors" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 253 }, { "type": "string", "enum": [ "" ] } ], "default": "" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceCompetitors", "summary": "Atomically replace the curated competitor set", "tags": [ "competitors" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "competitors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "type": "string", "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false }, "maxItems": 25 } }, "required": [ "competitors" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/competitors/{competitorId}": { "delete": { "operationId": "removeCompetitor", "summary": "Remove a tracked competitor", "tags": [ "competitors" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "competitorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/competitors/suggestions": { "post": { "operationId": "suggestCompetitors", "summary": "Discover competitor suggestions using stored project inputs and existing spend guards", "tags": [ "competitors" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/tracked-domains": { "get": { "operationId": "listTrackedDomains", "summary": "List the brand's owned domains", "tags": [ "tracked-domains" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addTrackedDomain", "summary": "Track an owned domain with existing classification safeguards", "tags": [ "tracked-domains" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "maxLength": 253 } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/tracked-domains/{domainId}": { "delete": { "operationId": "removeTrackedDomain", "summary": "Stop treating a tracked domain as owned", "tags": [ "tracked-domains" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/topics": { "get": { "operationId": "listTopics", "summary": "List project topics", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTopic", "summary": "Create a project topic", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "confirmProjectTopics", "summary": "Atomically confirm onboarding topics", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 10 } }, "required": [ "topics" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/topics/{topicId}": { "patch": { "operationId": "renameTopic", "summary": "Rename a project topic", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "topicId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteTopic", "summary": "Delete a project topic", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "topicId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/topics/suggestions": { "post": { "operationId": "suggestTopics", "summary": "Suggest topics grounded in the project's stored website and metadata", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/topics/accept": { "post": { "operationId": "acceptProjectTopics", "summary": "Replace the project's accepted topic set including explicit tags", "description": "Reuses the existing compatibility acceptance workflow. Topics absent from the supplied set are removed. Use confirmProjectTopics for the atomic onboarding confirmation contract.", "tags": [ "topics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "tag": { "type": "string", "maxLength": 60 } }, "required": [ "label" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 } }, "required": [ "topics" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts": { "get": { "operationId": "listPrompts", "summary": "List project prompts and tracking state", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "proposed", "archived", "all" ], "default": "all" } }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPrompts", "summary": "Add tracked prompts with plan caps and submission replay protection", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "topicId": { "type": "string", "format": "uuid", "nullable": true }, "texts": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4000 }, "minItems": 1, "maxItems": 300 } }, "required": [ "requestId", "texts" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceProjectPrompts", "summary": "Atomically replace and track the curated project prompt set", "description": "Uses the existing transactional onboarding confirmation RPC and workspace prompt budget. Replacing the set permanently removes prior prompts and their cascaded run history; use createPrompts or prompt lifecycle operations to retain history.", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "minLength": 1, "maxLength": 200 }, "queries": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 400 }, "minItems": 1, "maxItems": 300 } }, "required": [ "category", "queries" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "categories" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/generate": { "post": { "operationId": "generatePrompts", "summary": "Generate proposed prompts and topics with existing spend guards", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/suggestions": { "post": { "operationId": "suggestOnboardingPrompts", "summary": "Generate reviewable onboarding prompts without accepting them", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/{promptId}/accept": { "post": { "operationId": "acceptPrompt", "summary": "Start tracking a proposed prompt within plan limits", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/{promptId}/archive": { "post": { "operationId": "archivePrompt", "summary": "Archive or restore a prompt using the existing lifecycle", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unarchive": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/bulk": { "post": { "operationId": "changePromptsInBulk", "summary": "Track, archive, or restore a bounded prompt batch", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "action": { "type": "string", "enum": [ "track", "archive", "restore" ] } }, "required": [ "ids", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/{promptId}/topic": { "put": { "operationId": "setPromptTopic", "summary": "Assign a prompt to a topic in the same project", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topicId": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "topicId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/{promptId}": { "delete": { "operationId": "deletePrompt", "summary": "Permanently delete a prompt and its associated run history", "description": "This operation permanently removes the prompt and database-cascaded measurement history. Use archivePrompt to preserve historical results.", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/prompts/{promptId}/analysis": { "get": { "operationId": "getPromptAnalysis", "summary": "Read a prompt's measurement analysis", "tags": [ "prompts" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 366, "exclusiveMaximum": false, "default": 30 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1000 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4000 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/issues": { "get": { "operationId": "getIssues", "summary": "Read site audit findings and audit progress", "tags": [ "issues" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/audits": { "post": { "operationId": "enqueueAudit", "summary": "Enqueue a guarded site audit without executing worker ticks", "tags": [ "audits" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listAudits", "summary": "List audit history", "tags": [ "audits" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/issues/checklist/{code}": { "put": { "operationId": "setIssueChecklistItem", "summary": "Set an issue checklist item's completion state", "tags": [ "issues" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean" } }, "required": [ "done" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/opportunities": { "get": { "operationId": "listOpportunities", "summary": "Read current measured opportunities", "tags": [ "opportunities" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "done", "declined" ], "default": "pending" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/opportunities/{opportunityId}": { "patch": { "operationId": "setOpportunityStatus", "summary": "Mark an opportunity pending, done, or declined", "tags": [ "opportunities" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "done", "declined" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/opportunities/refresh": { "post": { "operationId": "enqueueOpportunities", "summary": "Enqueue guarded opportunity analysis without worker ticks", "tags": [ "opportunities" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/traffic/annotations": { "post": { "operationId": "createTrafficAnnotation", "summary": "Add a traffic chart annotation to the explicit project", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ga", "gsc" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "provider", "date", "label" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listTrafficAnnotations", "summary": "List annotations for a bounded date window", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "provider", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ga", "gsc" ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/traffic/annotations/{annotationId}": { "delete": { "operationId": "deleteTrafficAnnotation", "summary": "Delete a traffic chart annotation from this project", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "annotationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations": { "get": { "operationId": "listIntegrations", "summary": "Read integration metadata and non-secret configuration", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/{provider}/setup": { "get": { "operationId": "getIntegrationSetupUrl", "summary": "Get a browser URL for interactive provider consent", "description": "OAuth consent requires an interactive account session. Open the requested project from the Projects page, then open its Integrations tab and connect the provider. The API does not change a browser's selected project.", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "google_analytics", "google_search_console", "webflow" ] } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/{connectionId}/config": { "put": { "operationId": "configureGoogleIntegration", "summary": "Configure a pending Google connection and atomically queue backfill", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ga4PropertyId": { "type": "string", "minLength": 1, "maxLength": 200 }, "propertyName": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "ga4PropertyId", "propertyName" ], "additionalProperties": false }, { "type": "object", "properties": { "gscSiteUrl": { "type": "string", "minLength": 1, "maxLength": 2048 }, "siteName": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "gscSiteUrl", "siteName" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/{connectionId}/webflow-config": { "put": { "operationId": "configureWebflowIntegration", "summary": "Validate and configure an authorized Webflow collection", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "collectionId": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "bodyFieldSlug": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "externalIdFieldSlug": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "excerptFieldSlug": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "nullable": true }, "publishedAtFieldSlug": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$", "nullable": true } }, "required": [ "siteId", "collectionId", "bodyFieldSlug", "externalIdFieldSlug" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/{connectionId}": { "delete": { "operationId": "disconnectIntegration", "summary": "Disconnect Google or revoke Webflow authorization safely", "description": "Webflow disconnect requires the current generation in an If-Match header, for example If-Match: \"3\". Crawler sources use their dedicated endpoint.", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/google/properties": { "get": { "operationId": "listGoogleAnalyticsProperties", "summary": "List authorized Analytics properties without exposing credentials", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/google/sites": { "get": { "operationId": "listGoogleSearchConsoleSites", "summary": "List authorized Search Console sites without credentials", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/webflow/sites": { "get": { "operationId": "listWebflowSites", "summary": "List the authorized Webflow site", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/webflow/collections": { "get": { "operationId": "listWebflowCollections", "summary": "List an authorized Webflow site's collections", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "siteId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/integrations/webflow/collections/{collectionId}": { "get": { "operationId": "getWebflowCollection", "summary": "Read an authorized collection's fields and schema fingerprint", "tags": [ "integrations" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/crawler-sources": { "post": { "operationId": "createCrawlerSource", "summary": "Create a crawler source and reveal its token once", "tags": [ "crawler-sources" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/crawler-sources/{connectionId}": { "patch": { "operationId": "rotateCrawlerSource", "summary": "Rotate a crawler token with an expected-generation check; the previous token keeps working for 24 hours", "tags": [ "crawler-sources" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "rotate" ] }, "expectedGeneration": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "action", "expectedGeneration" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "revokeCrawlerSource", "summary": "Revoke a crawler source with existing race protection", "tags": [ "crawler-sources" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "integrations" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/optimization-proposals": { "get": { "operationId": "listOptimizationProposals", "summary": "Read retained optimization proposals and their frozen evidence", "tags": [ "optimization-proposals" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createOptimizationProposal", "summary": "Create a bounded proposal with frozen measurement evidence", "tags": [ "optimization-proposals" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetUrl": { "type": "string", "minLength": 8, "maxLength": 2048 }, "kind": { "type": "string", "enum": [ "plan", "content_diff" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "rationale": { "type": "string", "minLength": 1, "maxLength": 2000 }, "recommendedChange": { "type": "string", "minLength": 1, "maxLength": 8000 }, "evidence": { "type": "object", "properties": { "fromDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "toDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "snapshotDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true } }, "required": [ "fromDate", "toDate", "snapshotDate" ], "additionalProperties": false }, "rankFactors": { "type": "object", "properties": { "urgency": { "type": "string", "enum": [ "low", "medium", "high" ] } }, "required": [ "urgency" ], "additionalProperties": false } }, "required": [ "targetUrl", "kind", "title", "rationale", "recommendedChange", "evidence", "rankFactors" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/optimization-proposals/{proposalId}": { "patch": { "operationId": "decideOptimizationProposal", "summary": "Approve, reject, or revoke a proposal using existing version/hash guards", "tags": [ "optimization-proposals" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject", "revoke" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "nullable": true } }, "required": [ "decision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content": { "get": { "operationId": "listContent", "summary": "List content projects with cursor pagination", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "article", "blog_post", "linkedin", "youtube_desc", "product_release" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "draft", "in_review", "published", "archived" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createContent", "summary": "Create an Article or writer-brief project idempotently", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 12000 }, "type": { "type": "string", "enum": [ "article" ], "default": "article" }, "sourceOpportunityId": { "type": "string", "format": "uuid", "nullable": true }, "specification": { "type": "object", "properties": { "outputMode": { "type": "string", "enum": [ "full_article", "content_brief" ] }, "funnelStage": { "type": "string", "enum": [ "tofu", "mofu", "bofu" ] }, "format": { "type": "string", "enum": [ "topic_guide", "how_to_guide", "ranked_list", "comparison", "alternatives_guide", "case_study", "checklist", "review" ] } }, "required": [ "outputMode", "funnelStage", "format" ], "additionalProperties": false } }, "required": [ "requestId", "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}": { "get": { "operationId": "getContent", "summary": "Read a content document and revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteContent", "summary": "Delete a draft while preserving publication boundaries", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/status": { "patch": { "operationId": "setContentStatus", "summary": "Set draft, review or archived state", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "in_review", "archived" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/tags": { "patch": { "operationId": "setContentTags", "summary": "Save tags against an expected document revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 240 }, "maxItems": 20 } }, "required": [ "expectedRevision", "tags" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/title": { "patch": { "operationId": "setContentTitle", "summary": "Save a title against an expected document revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "title": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "expectedRevision", "title" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/document": { "put": { "operationId": "saveContentDocument", "summary": "Save blocks and title against an expected revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "body": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "h1", "h2", "h3", "p", "bq", "ul", "ol", "key-takeaway", "table" ] }, "text": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" }, "maxItems": 200 }, "header": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "maxItems": 100 } }, "required": [ "type" ], "additionalProperties": false }, "maxItems": 2000 } }, "required": [ "expectedRevision", "title", "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/brief": { "put": { "operationId": "saveContentBrief", "summary": "Edit the writer brief against an expected brief revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedBriefRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "prompt": { "type": "string", "minLength": 1, "maxLength": 12000 } }, "required": [ "expectedBriefRevision", "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/studio": { "get": { "operationId": "getContentStudio", "summary": "Read bounded Studio context, proposals, readiness and delivery state", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/messages": { "get": { "operationId": "listContentMessages", "summary": "Read the latest 100 content messages with truncation metadata", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/questions": { "post": { "operationId": "getContentSetupQuestions", "summary": "Create or replay deterministic content setup questions", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/sources": { "post": { "operationId": "addContentSource", "summary": "Verify and attach a public source idempotently", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "requestId", "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/sources/{sourceId}": { "delete": { "operationId": "removeContentSource", "summary": "Remove a source from this content project", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sourceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/proposals/{proposalId}/decision": { "post": { "operationId": "decideContentProposal", "summary": "Accept or reject a revision proposal", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "decision": { "type": "string", "enum": [ "accepted", "rejected" ] } }, "required": [ "expectedRevision", "decision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/history": { "get": { "operationId": "listContentHistory", "summary": "List 20 edit versions with a revision cursor", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "beforeRevision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/history/{versionId}": { "get": { "operationId": "getContentVersion", "summary": "Preview a saved version of this document", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/history/{versionId}/restore": { "post": { "operationId": "restoreContentVersion", "summary": "Restore a saved version against an expected revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/readiness": { "post": { "operationId": "checkContentReadiness", "summary": "Record readiness for the exact current document and sources", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "expectedSnapshotHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "expectedRevision", "expectedSnapshotHash" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/generation": { "post": { "operationId": "generateContent", "summary": "Queue idempotent initial generation or a scoped revision", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "generate" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "expectedRevision": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "answers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4000 }, "maxItems": 10, "default": [] }, "instruction": { "type": "string", "minLength": 1, "maxLength": 4000 }, "scope": { "type": "object", "properties": { "blockId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false, "default": {} } }, "required": [ "requestId", "expectedRevision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/generation/{jobId}": { "get": { "operationId": "getContentGeneration", "summary": "Poll a durable generation job and resulting proposal", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/approval": { "post": { "operationId": "approveContent", "summary": "Approve the exact current ready-to-publish version", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "publish" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedUpdatedAt": { "type": "string", "format": "date-time" }, "expectedHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "expectedUpdatedAt", "expectedHash" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/publishing": { "post": { "operationId": "publishContent", "summary": "Queue an approved version for Webflow draft or live delivery", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "publish" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "expectedHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "action": { "type": "string", "enum": [ "draft", "publish" ] } }, "required": [ "versionId", "expectedHash", "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "getContentPublishing", "summary": "Read approval and paginated provider delivery status", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 100 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/content/{contentId}/publishing/retry": { "post": { "operationId": "retryContentPublishing", "summary": "Retry an eligible delivery while retaining approval safeguards", "tags": [ "content" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "write", "publish" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" } }, "required": [ "jobId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/overview": { "get": { "operationId": "getAnalyticsOverview", "summary": "Visibility per AI platform", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/visibility": { "get": { "operationId": "getAnalyticsVisibility", "summary": "Visibility over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/visibility-ranking": { "get": { "operationId": "getAnalyticsVisibilityRanking", "summary": "Competitor visibility ranking", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/visibility-competitors": { "get": { "operationId": "getAnalyticsVisibilityCompetitors", "summary": "Competitor visibility over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/share-of-voice": { "get": { "operationId": "getAnalyticsShareOfVoice", "summary": "Share of voice by competitor", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/share-of-voice-series": { "get": { "operationId": "getAnalyticsShareOfVoiceSeries", "summary": "Share of voice over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/average-position": { "get": { "operationId": "getAnalyticsAveragePosition", "summary": "Average mention position over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/position-ranking": { "get": { "operationId": "getAnalyticsPositionRanking", "summary": "Average-position ranking", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/topic-rankings": { "get": { "operationId": "getAnalyticsTopicRankings", "summary": "Topic rankings and prompt positions", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/topic-breakdown": { "get": { "operationId": "getAnalyticsTopicBreakdown", "summary": "Overview topic visibility and citation breakdown", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/topic-distribution": { "get": { "operationId": "getAnalyticsTopicDistribution", "summary": "Topic distribution", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/topic-positions": { "get": { "operationId": "getAnalyticsTopicPositions", "summary": "Topic positions by engine", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/models": { "get": { "operationId": "getAnalyticsModels", "summary": "AI platform comparison matrix", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/metric-series": { "get": { "operationId": "getAnalyticsMetricSeries", "summary": "Selected canonical metric by platform", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "visibility_pct", "share_of_voice_pct", "avg_position", "citation_share_pct", "sentiment_avg" ], "default": "visibility_pct" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/mentions": { "get": { "operationId": "getAnalyticsMentions", "summary": "Own-brand mention trend", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citations": { "get": { "operationId": "getAnalyticsCitations", "summary": "Own-domain citation trend", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/sentiment": { "get": { "operationId": "getAnalyticsSentiment", "summary": "Sentiment over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/sentiment-breakdown": { "get": { "operationId": "getAnalyticsSentimentBreakdown", "summary": "Sentiment scores and themes", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/sentiment-stacked": { "get": { "operationId": "getAnalyticsSentimentStacked", "summary": "Positive, neutral and negative sentiment over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/perception": { "get": { "operationId": "getAnalyticsPerception", "summary": "Latest Searchly brand-perception assessment", "description": "Returns the latest persisted Searchly assessment for the selected engine; this is separate from an observed answer capture.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ], "default": "gpt" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/head-to-head": { "get": { "operationId": "getAnalyticsHeadToHead", "summary": "Brand and competitor comparison", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-share": { "get": { "operationId": "getAnalyticsCitationShare", "summary": "Citation share over time", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-domains": { "get": { "operationId": "getAnalyticsCitationDomains", "summary": "Citation domain ranking", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-pages": { "get": { "operationId": "getAnalyticsCitationPages", "summary": "Top cited pages", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-types": { "get": { "operationId": "getAnalyticsCitationTypes", "summary": "Cited content-type breakdown", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "earned_media", "social", "owned", "institution", "pr_wire", "other", "competitor" ] }, "maxItems": 7 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-domain-series": { "get": { "operationId": "getAnalyticsCitationDomainSeries", "summary": "Citation-domain trends", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "earned_media", "social", "owned", "institution", "pr_wire", "other", "competitor" ] }, "maxItems": 7 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/cited-urls": { "get": { "operationId": "getAnalyticsCitedUrls", "summary": "Cited URLs and source classifications", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "earned_media", "social", "owned", "institution", "pr_wire", "other", "competitor" ] }, "maxItems": 7 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/citation-gap": { "get": { "operationId": "getAnalyticsCitationGap", "summary": "Competitor citation-domain gaps", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "earned_media", "social", "owned", "institution", "pr_wire", "other", "competitor" ] }, "maxItems": 7 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/content-type-gap": { "get": { "operationId": "getAnalyticsContentTypeGap", "summary": "Competitor content-type gaps", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "categories", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "earned_media", "social", "owned", "institution", "pr_wire", "other", "competitor" ] }, "maxItems": 7 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/position-distribution": { "get": { "operationId": "getAnalyticsPositionDistribution", "summary": "Mention-position distribution", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/funnel": { "get": { "operationId": "getAnalyticsFunnel", "summary": "Decision-journey funnel breakdown", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/fanouts": { "get": { "operationId": "getAnalyticsFanouts", "summary": "Observed query fan-outs", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/site-health": { "get": { "operationId": "getAnalyticsSiteHealth", "summary": "Site health and audit history", "description": "Uses the same selected reporting methodology and evidence helpers as the platform. Dates are inclusive UTC calendar dates, bounded to 366 days; omitted dates select the last 7 days. Entity lists are paginated with at most 100 rows, dated time series retain up to 366 points, and limited nested entity lists are identified explicitly.", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/analytics/prompts/{promptId}": { "get": { "operationId": "getPromptAnalytics", "summary": "Analyze one project prompt", "tags": [ "analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/answers": { "get": { "operationId": "listAnswers", "summary": "List raw observed answers with collection provenance", "tags": [ "answers" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/answers/export": { "get": { "operationId": "exportAnswersCsv", "summary": "Stream raw answer history as CSV", "tags": [ "answers" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "style": "form", "explode": false }, { "name": "platforms", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "gpt", "claude", "perplexity", "gemini", "ai_overview" ] }, "maxItems": 5 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/answers/{answerId}": { "get": { "operationId": "getAnswer", "summary": "Read an immutable answer capture and its provenance", "tags": [ "answers" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "answerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/answers/{answerId}/citations": { "get": { "operationId": "listAnswerCitations", "summary": "Read parsed answer citations with pagination", "tags": [ "answers" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "answerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/answers/{answerId}/mentions": { "get": { "operationId": "listAnswerMentions", "summary": "Read parsed answer mentions with pagination", "tags": [ "answers" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "answerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/traffic/ga4": { "get": { "operationId": "getGa4Traffic", "summary": "Read Google Analytics traffic and receipt coverage", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/traffic/gsc": { "get": { "operationId": "getSearchConsoleTraffic", "summary": "Read Search Console traffic and receipt coverage", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/traffic/ga4/breakdowns": { "get": { "operationId": "getGa4Breakdowns", "summary": "Read GA4 pages, devices, acquisition and countries", "tags": [ "traffic" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } }, { "name": "aiOnly", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/crawler-sources": { "get": { "operationId": "listCrawlerSources", "summary": "Read crawler connection state without credentials", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/crawler-events": { "get": { "operationId": "listCrawlerEvents", "summary": "Read retained crawler events with bounded pagination", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/evidence": { "get": { "operationId": "getPageEvidence", "summary": "Join observed answer citations, AI referrals and search traffic on one evidence day", "description": "Requires an explicit UTC snapshot date. Uses the platform's bounded receipt-backed source helpers and URL-path association; this does not attribute a visit to a specific answer. Source counts, answer-cell coverage and truncation are explicit. Missing measurements remain null unless complete source evidence establishes absence. Pagination covers the joined available rows.", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/pages": { "get": { "operationId": "listPageRecords", "summary": "Read Page Records with activity pagination and evidence coverage", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 100000, "exclusiveMaximum": false, "default": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/page": { "get": { "operationId": "getPageRecord", "summary": "Read a Page Record for a precise project URL", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "maxLength": 2048 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/agent-analytics/rechecks": { "get": { "operationId": "getPageRechecks", "summary": "Read bounded active, completed and failed rechecks", "tags": [ "agent-analytics" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 100, "exclusiveMaximum": false, "default": 50 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/shopping": { "get": { "operationId": "getShoppingReport", "summary": "Read the AI shopping report for a date window", "description": "Reports the products ChatGPT showed in the project's measured answers: totals, the previous window's totals, daily series, tracked brands, retailers, products, prompts, searches and labels. Counts only; derive rates from their numerators and denominators. Dates are inclusive UTC run dates, at most 366 days; omitted dates select the last 30 days. The previous window defaults to the equal-length window before from; previous is null when it ends before capture started. Topics filter to prompts in those project topics. Before capture starts, capture.first_captured_on is null and every total is 0.", "tags": [ "shopping" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "previousFrom", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "previousTo", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/shopping/prompts/{promptId}": { "get": { "operationId": "getShoppingPromptEvidence", "summary": "Read the product shelves ChatGPT showed for one prompt", "description": "Returns up to limit (at most 20) of the prompt's captured answers in the window, those with products first: each shelf in ChatGPT's order, its searches and an answer excerpt. Answer text and product data are third-party content.", "tags": [ "shopping" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 20, "exclusiveMaximum": false, "default": 20 } } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{projectId}/shopping/product": { "get": { "operationId": "getShoppingProductEvidence", "summary": "Read every appearance of one product in ChatGPT answers", "description": "key is a product's key from the report. Returns its attribution and up to 100 appearances in the window, newest first, with position, price, retailer and link. Topics filter as in the report. Returns 404 when the product has no appearance in the window and topics.", "tags": [ "shopping" ], "security": [ { "apiKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "topics", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 100 }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Operation completed. JSON payloads are wrapped in data; collection payloads include their pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "201": { "description": "Resource created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "202": { "description": "Work queued. Poll the operation's documented status endpoint; acceptance is not completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "default": { "description": "A stable error code and request ID; 429 and temporary queue denials can include Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Searchly API key. Supported scopes: read, write, generate, publish, integrations." } }, "schemas": { "Success": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": {}, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Error": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Meta": { "type": "object", "required": [ "requestId" ], "properties": { "requestId": { "type": "string", "format": "uuid" } } } } } }